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EDITOR'S DESK 


By Dave Mark EdUor-in-Cbief 


First, A Note From The Publisher’s Desk 

It’s not often that I get to write, I did want to toucli 
base with you, our readers, tliis month on a couple of notable 
events here at MacTecb Magazine. 

First, as you will see later in diis issue, we're winding down 
the Programmer’s Challenge. As tlie Challenge is now 10 years 
old, Bob wants to spend more time witli liis family. We wish Bol> 
all tlie l:)est, and give liim a heaity "tliank you” for all the effons 
he's made in helping us le^u-n to program more efiicientJy. 

We are considering new kinds of puzzles and contents, 
what’s doable, and what's not. If you have ideas or feedback 
on what you'd like to see, drc}p u.s a line. 

Hello (again) Dave! 

As you probably already heard, and see below, we 
welcome back I>ave Mark with open arms. Dave is coming 
hack not only with the “Getting Started’’ column, but as our 
new Editor-in-chief. 

WeVe thrilled to have Dave on board again. Well 
continue to cover the kinds of tilings you want, from 
REALbasic to CodeWarrior, from Scripting to Network 
Administration topics. And, we 11 look to have even more 
fun along the way. We’re looking for feedback from you all! 

Neil Ticktin, Publisher 


Good to be Back 

Ten years ago, lx.fore the net was liig, lx.fore Rhapsody, 
liefore Copland, even before Greg Galanos and company liegal 
CodeWarricjr, I had a diance encounter with my gotxl friend <and 
your failliful publisher) Neil Ticktin. If mejiiory serves, Neil was at 
MacWorld having just put the finishing touches on his cleal to 
purchase a then struggling magazine, known as MacTulor, s<x>n to 
become MacTech. Neil was a blizzard of activity, signing this and 
doing that, and 1 got sucked into the maelstrom. 

For those yc^ung pups in the crowd, 1 used to be a regular 
in MacTech. Wrote a column called Getting Started, and another 
called "From the Factory' Floor", 

Wrote a bunch of books as well. If you don't know' me, 
maybe you've suimhled across a well-worn copy of "Learn C 
on the Macintosh" or one of the "I'he Macintosh Programming 
Primer" series. 

Since my days with MacTech, Pve done a \ai of 
adventuring. 1 hooked up with Metrowerks, had a lot of fun 
there, met some awesome people. Metrowerks up and sold 
themselves to Motorola, time to go, started up another startup 
with some friends (buy me a drink at the next MacWorld or 
WWDC and I’ll tell you all about that roller-coa.sler ride!) 


Somewhere about a year ago, the events started unfolding 
that [>rought me hack here. 

Way hack when, Vd played with all the Rhapsody betas, 
run the early Mac ports of Project Builder and Interface 
Builder, messed arc}und wilh Objective-C. But, I don’t know, 
none of it really rang true for me. 

Then, about a year ago, a friend of mine gave me his 
cube, just so I could play with the Mac OS X beta. 1 was 
skeptical. And then Apple shipped the Titanium PewerBooks. 
And 1 fell in love all over again. 

So I'm out in California visiting my buddy Neil, and he 
planLs the seed. "Dave". "Dave". "Come back, Dave". "Write more 
books". "Start writing your Getting Started column again", "I'll 
even make you Editor-in-Chief, Dave". LOL. Well, maybe it 
wasn't quite like than But close. : ) 

So here 1 am. Back in the fold. Enjoying the heck out of my 
Mac, Doing a tremendous amount of learning, lliere is SO much 
cool stuff to play with now. C(k> 1 NFW stuff, like Cocoa, 
Objective-C, and Objective-C++. Amazing Java and REALl>asic 
apps that feel totally natural running under X. My old friends 
AppleScript and QuickTime are .still here and incredibly w'ell 
integrated into this new environineni. 

On the hardware side, Apple has really hit their .stride. 
Tlie digital hull .strategy makes sen.se to me. There’s a 
gorgeous, foeu.sed lineup of machines, each outdoing its 
predecessor. USB and FireWire are also well integrated and 
ubiquitous enough in the consumer electronics world to make 
the digital hub a realistic strategy And the iPod? The iPod is 
like the icing on the cake. 

Bottom line, ihere^s a lot of cool stuff happening and I am 
really having a blast playing with all these cool toys and learning 
to program my Mac all over again. 

As you can see if you turn the page a bit, I've started my 
monthly Getting Started column once again. But this time 
around, my involvement with MacTech is going to be quite a 
bit deeper. Part of my role as Editor-iii-Chief is to reshape the 
magazine, to find ways to make MacTech Magazine more 
useful to you. 

To that end, we've created an ejiiail address that goes riglit 
to my doorstep: feedback@maGech.CGm 

Please take a minute or two to drop me a line. Let me know' 
w'hai you like and dislike about the magazine. Want more OS X- 
centric content? Mtire on C^^arhon? Flow' about tcipics like PI IP and 
mySQL? Though I can't promise to reply to every email, I wall 
promise to read ever> one of them. 

Ail that said, it is great to be back in the fold. I am really 
liKiking forward to working mih you all again. 

From the Editor^s chair,. 

Dat^e Mark 
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MAC OS X COM 
2002 


By Vicki Broiim 

Report on the 1st O’Reilly Mac OS X Conference 


Imagine.., 

Ima^nc the intrcxliiciorv session of a technical conference. 
Approximately seven hundred developers and users watch and 
listen as the speaker welcomes tliem to four days of interesting talks 
given by experts in tlie field. The rcx>m is softly lit by the screens of 
hundreds of laptop computers, alxiiit one for every two attendees. 
The majorit>^ of the laptops are white iBooks and Tuaniuin 
Power1x>oks, with a sprinkling of older Powertxxiks and iBtx^ks 
here and tliere. Every screen you see is running Mac OS X. 

The session raxiLs and the break ;irea are provided wiili open 
wireless connectivity, lx)tli Ix^tween systems at tlie conference and 
to the Internet. Every session r(x>m Is outfitted with Macintosh 
Itaidware and a Cinema display, but mast of the speakers bring their 
own Powerlxxjks. (]onnecting tlie Powerixx)ks to the projetlion 
facilities is e^isiiy done; the tech crew all understand Macintosh. 

Attendees scan the progrtiiiL Sessions this week indixle 
keynote 5es.sions by David Pogue (NY Times I'echnology Columnist 
and Mac Author/Publisher), James Gosling (V.P. and Fellow at Sun, 
co-inventor (^f Java, etc,), Dan Gillmor (San Jose Mercury News 
Technology Columnist, Jordan Hubbard (Manager of BSD 
Technologies, Apple Computer), Wilfredo Sanchez Vega (Darwin 
Developer) and Mark Frueiifelder (writer and illustnitor). 

Technical sessioas cover Cocoa pnignimming, Aqua. Quartz, 
QuickTime. Open Souae and Darwin, Java, We^>Ohjec^s, Mac OS X 
Server, iPliolo, Rendezvous, Apple Help, and AppleScript, Less 
technical sessioas dLscuss end-u.ser troubleshcxjting, wliat'.s new in 
Jaguar, an overview of Mac OS X for Mac OS 9 users, and a Mac OS 
X “report canT" (presented f>y Adam Engsi, editor ofTidBlTs). 

Tills Isn’t Ap[>le’s ’World Wide Developer Cx^nference, but it is 
definitely a deveioper-oriented conlerenc'e. Nor Ls it MacHack; there 
is hackery, to be sure, but it mcxstly happens during tlie tbylight 
hours. And, of course, this Lsnl MacWfirid; the tiny exhibit space and 
strong technical fixers lx)lii emphasize that fact. 

In short, tliis Ls the first annual Mac OS X Omferenct;, held by 
Q'Reilly ik As.s<xiates from Sept. 30 ^ Oct. 3, 2002 in Santa Clara, CA. 
O'Reilly & As.s(xiates, a well-known publisher of lxK>ks on Unix and 
open source topics such as l^erl. Python, Linux, Apache, and many 
others, has also become known as a presenter of excellent techiiic^al 
conferences. Notable O’Reilly offerings have included several Open 
Source amvenlions, the Emerging Teclinologies conference, as well 
as conferences on Bioinfonmtics, Java, and Peer-to-Peer services. 


Although Tim O’Reilly (founder and president of O’Reilly 8l 
Associates) is not a developer liiniself, he is an avid follower of 
technology and teclinologLsts. In fact, he claims tliat much of lus 
business model Ls Ixtsed on Ibllowing the activities of ^'Alphit Geeks", 
the techies wiio always seem to ^get tliete first" on any new and 
interesting teclinoiogy. 

Originally focusing on Unix^spedfic topics, O’Reilly Ik 
Asscxiates has publLshed a numlxfr of bex^ks on cross-pbtform 
technologies (such as Bioinfomiatics, Java and XML) as well as 
publications on the Windows and MadntcKh platforms. Mac OS X 
brings many of O’Reilly’s areas of interest together; the first Mac OS 
X cx>nference wus an opportunity for O'Reilly to bring practitioners 
of tliose interest areas together to share knowledge and expertise. 

iNTRODOCnON 

'Hie conference [,m)gram provided tfiis intixxfiiction: 

Welcome to ourftt'sl conference focusing on Mac OS X, one 
of the most visionary practical things bappetiing in the 

industry^ today . Jitsl m programming tmls and applications 

now share common ground in Mac OS X, thu conference brings 
Mac, Unm'oimt source, Java, and other practitioners into the 
same space... It's an event designed to sj^eed your tmmition or 
introduction to the 21.a centufy ojTerating system. 

Tim O’Reilly Ls alst) quoted Con the program ct}ver) its saying: 

Mac OS X is the first true 21st century^ platform, The BSD 
Unix undef^mmings bring stability ami a rich ofKoi source 
heritage; the Aqua interjdce brings Apple's longstanding expertise 
in user exfKmence, The iApps. 802.11 wireless support, and peer- 
to-peer features like Rendezmiis show that Apple basnl lost its 
touch when it comes to putting the future of computing into a 
'sleek, imunely great' package. 

Any developer who isn’t tracking Mac OS X ought to have his 
head exiimined. 

The Sessions 

O’Reilly called this a conference for developers, power users, 
hackers and network administrators, and it definitely was. There 
was something for each of these groups, and several otlier 
categories besides. 


Vicki Brawn has been using Unix systems since 1983 and Mac OS since 1986. She is delighted that Mac OS X gives her the opportunity to use both 
at the same time. 
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Mac os X In the Lvrge 


For users new to Mile OS X, there were several talks to chtxjse 
from, including David Pogue’s ""Welctjme lo Mac OS based on 
his lxH:)k ""Mac OS X: The Missing Manual" (puhlLshed by O’Reilly). 
This session was part of a track entitled *‘Mac OS X in the Laige”. 

Other sessions in this track included Adam Engst’s "Mac OS X 
Report Card", a .session entitled "End-user Troubieshcxiting for Fun 
and Profit” (based on the Ixxak, ‘‘Mac OS X Disaster Relief' by Ted 
liindau and Dan Fnikes), and the “Cult of the Mac”, presented by 
Leander Kahney (joumalLst for Wired News and former senior writer 
for MaeWeek). Two well^attended tips and tricks talks: “Trickedoiit 
X: Mow do Alpha MacGeeks Arrange llieir OS X Workspace” and 
“Mac OS X Hacks” proved popubr botli with audience members 
and multiple panelists showing ofl^ their favorite tricks. 

User Interface; Programming 

Develofx^rs could attend their choice of two dozen sessions on 
user interlac'e design or Mac OS X pnogramming, as well as six 
different programming tutorial choices on Monday, Tutorials 
cxwered AppleScript, Objeclive-C, Java, Perl, and Programming 
Oxxxi (in Objective-C or Perl), 

Conference sessioas included “Adopting the Mac OS X User 
Experience in your Application", a 4>minote run-thn>ugh of the 
Aqua Human Interface Guidelines presented by John Geleyase, 
Apple’s user experience evangelist in Worldwide Developer 
Relatioas. This was immediately followed by a related talk, "Mac 
User Interface Design for New Developers" presented by Brtx^k 
Conner, author of the fonlicoming book "Programming Quartz: 
Advanced 2D Graphics on the Macintosh”. 

Other sessions covered Java Media, RealBasic, Objective-C, 
Quartz, and using AppleScript (or Peri) to automate workflow. 
Cocoa was presented in several sessions, ranging from “An 
Intnxluction to the t2ocoa Document Architecture” to “API 
Techniques" to "Getting Diita Onscreen with Cocoa”. 



Fetch 


Servers and Networking; Multimedia 

Two complementary tracks included over a dozen 
presentations, including sessions on Open Directory/LDAF, Neilnfo, 
Rendezvous, and the Open Source ckttabases available for Mac OS 
X. Several sessions addressed the creation of web sites. Derrick Story 
and Rael Domf'est’s session, “Building a Mac-Based Web Site”, 
discussed secrets for QuickTime video, online iPhoio slide shows, 
and the best ways to make large tilCuS available to others without FTP 
access. This was followed by Don Smith’s "Serving Your Site from a 
Mac”, which discussed Uie use of Apache and numerous additional 
free tools attendees could use to fmild a web site on Mac OS X. 

Several sessions were avaUable for users of WebObjeds, 
including a half-day tutorial introduction to WebObjects Tools and 
Techniques, a 45-minute WebObjects technical overview, and a 
discussicin of Rapid Application Development using WebObjects. 
Finally, for those who wanted a bit more fun, Damien Stolarz 
presented "How to Put up your Own TV Station on the Internet 
with Mac OS X”. 


dog. 



Fetchsoftworlcs.com 



Hardware 

Several playful sessions focused on hardware. Dori Smith 
discussed how to build a Mac clone that will run Mac OS X for “a 
fraction of both the price and the looks” of Apple hardware; the 


Version 4.0.2 now available. 
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session was appropriately entitled "Bnikliiig a Cheap, Ugly Mac^ 
I'ed Stevko provided two ways to create rolxjts itsing a Macintosh 
in "Frankentosh: Creating Rolx)ts on the Mac"". 

Kent Salas shared hLs heivily mfxlified G4 (with an LCD light- 
show panel, hiue interior ligliLs, anti firewire/USB ports on the front 
panel; http://www.kentsalas.LOiTL^>lLie!ceg4) in “Mac Mechanical 
Mayhem, or 1 low to Completely \bid Yotir Mac’s Wiimtnty'Hie talk 
was well attended and quite a few attendees stayed into tlie break 
to talk alxjut mods with Kent. 


UNIX 

Perhaps unusual for a Mac OS conference (but le^s unusual for 
either O’Reilly or Mac OS X), one track was simply chilled Unix. 
Sessions in tills track ranged from “Mac OS X for tlie Common Unix 
Folk” to “Migratijig fhan Linux to Mac OS X” to “Mac OS X is Just 
Another Unix: Writing Pcirtable Applications”. The session entitled 
“From Unix to Aqua; Porting Large Unix Applications to \!ac OS X’ 
aiuld just as easily have listed in the User Interface track as this one. 

The Unix track addfessed one of the newest {!>ui steadily 
grtiwing) groups of users adopting Mac OS X - the traditional Unix 
(Sun, Linux, BSD, etc,) users, Tim O’Reilly has commented that 
“Apple's ’Switch* ad campaign focuses on people making tlie switch 
from Windows, but it may be the case that there’s an even laiger 
wave of switchers from Linux and other Unix platforms.” While it is 
the case that many UNIX users have used the Mac in the past, they 
have previously needed to keep two computers on their desks in 
order to work with both Mac OS and Unix. With Mac OS X, this is 
no longer the case; long-time UNIX users are trying out Mac OS X 
and discovering that they like it, 

'Hie patiel session, “Introducing tlie Mac User Ck)[Tiniunit>' to 
Unix Developers” (part of the “In the Laige” track) was meant to 
liring Unix developens togetiier witli traditional Mac OS developers. 
The session focused on what Mac OS X developers coming from 
Unix backgrounds need to know about tlie pMosophy of tlie Mac 
and tlie tjrientation of the Mac communiry. PanelLsts discussed 
simikirities and differences Ix^twc’en die Unix and Mac OS user 
communities and talked about what each group can do for die other. 

CuosE^G Thoughts 

I enjoyed this conference. IVe been to many technical 
conferences, but this was the first where everyone wils like me, in 
that everyone used a Mac and everyone, even the presenters, used 
Mac OS X, I admii tku WWDC is certainly Mac-oriented in its 
presentaiiotxs, but diase sessions are given by Apple, This conference 
was by and lor developers and power users, again, people like me. 

The only drawback 1 can mention is that 1 often couldn’t decide 
wiiich session to attend! Multiple tracks can cause that sort of 
difficulty. But as the week drew to a close, I was already wondering 
wliat interesting talks, tutorials, presenmtions, and panels will Lie in 
store next year. I’ll lie there. You should lie sure to attend too. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westjbrd, MA 


Penultimate 

When I look over this column from Mike Scanlin back in 
June^ 1995t I had no idea that I would still be writing it seven 
and one-half years later. Running the Programmer’s Challenge 
contest has been both a rewarding and an increasingly 
demanding experience, but the time has come for me to move 
on. The title of this column, my 90^^^, refers, not to the name of 
a new Challenge, but to the fact that my next column will he the 
last one. Besides announcing the winner of my final Challenge, 
the October Area Challenge, next month will include a 
retrospective on the Programmer's Challenge, the problems, the 
contestants, the evolution of the column, and perhaps a few 
anecdotes. Until then, I hope you have enjoyed reading the 
column as much as I have enjoyed writing it, 

Winner of the SeffembeRj 2002 Challenge 

The August, 20(X), Challenge problem asked readers to write 
code that would solve a sequence of chess end-game positions. 
Unfortunately, the problem must have been too difficult, and no 
entries were submitted. 1 thought somecMie miglit have adapted 
and extended the code from the problem in my first cokmin, the 
June, 1995, Check Checkmate Challenge, but this was not to be. 
Perhaps an omen . 

So, taking advantage of an extended deadline for this issue, 
we will look at the winner of the SeptemlK^r PhotoMosaic 
Challenge. Announced with a tongue-in-cheek reference to the 
25^^ anniversary of the death Cor aliduction by aliens, whichever 
you chc:>ose to believe) of ElvLs, this problem asked readers to 
generate a mosaic of smaller images that approximated a target 
image. CongratulaiicDns, cjtice again, to Ernst Munter (Kanata, 
Ontario), for submitting the fa.stesl and most accurate mosaic 
generator. 

Both Emsl and second-place finisher Jan SchoLsman use the 
Altivec programming model. Ernst divides the elements and 
images into “spots" of 4 pixels by 4 pixels, which allows one 
color plane of the spot to be represented in 64 biLs - 8 bils/color 
for each of the 16 pixels. The image elements used to construct 
the mosaic are divided into “slices'", or portions of the element 
corresponding to the desired tile size, and the slices are sorted 
by luminence, Ernst uses the luminence of a tile in the target 
image to select a position in the sorted slice array, and searches 
within die array to find the most appropriate slice. The depth of 
the search is limited to control execution time. The slice is 
seleaed to minimize the distance from the target image in RGB 
space. There are additional refinements to the algorithm, as 
described in the extensive commentary contained in the code. 

1 tested die entries submitted using twelve test cases, using 
three sets of mosaic elements, one set from lighthouse photos 1 


uxik at Isle au Haut, another set from pictures taken by my son 
on a trip to France, and the last set from pictures taken in die 
British Virgin Islands. Ernst’s solution produced better mosaics 
in 9 of the 12 test cases, and used significant less execution time 
than the second-place entry. Below, I have posted an example 
mosaic produced by Ernst's code, along with the origimil image, 
at the MacTech web site asi 

http://wvwv.mactechxom/progchallenge/WEnningMosaic/Outputlmage^^ 

and 

http://www,mactechxom/progchallengeAA/lnningMosaic/lnputlmage.jpg. 

The table below lists, for each of the solutions submitted, 
the number of test cases processed correctly, the total distance 
lietwecn pkL4s of the mosaic and die target image, execution 
time in niillLseconds, and the total score for each solution. As 
usual, the numlier in parentheses after the entrant's name is die 
total number tif Challenge points earned in all Challenges prior 
to this <me. 


Name 

Cases 

Distance 

Time 

Score 


Correct 


(msecs) 


Ernst Munter(8H2) 

12 

15598 

92522 

16914 

Jan Schotesnian 118) 12 

1^754 

337847 

22198 

'I'ony Cot)per (20) 

12 

isez'i 

440358 

25951 


Top Contestants 

Listed here are the Top Contestants for the Programmer’s 
Challenge, including everyone who lias accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants, 


Rank 

Name 

Points 

Wins 

Total 



(24 mo) (24 mo) 

Points 

1 , 

Munter, Ernst 

241 

8 

902 

2. 

Saxton, Tom 

65 

2 

230 

3. 

Taylor, Jonathan 

54 

2 

90 

4. 

Stenger, Allen 

53 

1 

118 

5. 

Hart, Alan 

34 

1 

59 

6. 

Cooper, Tony 

27 

1 

27 

7. 

Rieken, Willeke 

22 

1 

134 

8. 

Sadetsky, Gregory 

22 

0 

24 

9. 

Landsbert, Robin 

22 

1 

22 

10. 

Schotsman, Jan 

21 

0 

28 

11. 

Gregg, Xan 

20 

1 

140 

12. 

Mallett, Jeff 

20 

1 

114 

13. 

Wihlborg, Claes 

20 

1 

49 

14. 

Truskier, Peter 

20 

1 

20 
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• Shares files and printers 
between Macs and PCs 

• Supports Microsoft 


• Offers fully integrated 
and efficient browsing 

• Insures compatibility 


Community College System explained, !_; 
"'We didn't have lime to learn another ‘ j 
network operating system. The Macs | 
needed to fit seamlessly and efficiently I 
Into our district’s computer network, 
which used Windows NT file servers. i 
DAVE was the answer ” ^ 


standard NTFS file 
format 

• Provides three security 
options 


with Services for 
Macintosh 

• Provides NT Domain 
Login 



WWW. thursby. com 


“DAVE not only 
supports 

Macintosh computers 
still running OS 9, 
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Jaguar's SMB 
capabilities for 
the advanced and 
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If, 


“DAVE is, without any 
doubt, the best solution 
for integrating your Mac 
into a PC environment.” 

•Univers Macworld 
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Here is Ernst winning PhotoMosaic solution. 

M0SAIC-V2.CP 

Copyiight © 2002 
Ernst Munter 

t 

"Photo Mosajc"" 

VcfSiOrt 2 

The Lisk is to assemble a photomosaic resembtiog a "dcsiitrd ima^" from tiles ait 
out from a number of "element images" The eriieria ane closeness of the fit 
in terms the color distance (RMS sum of the RGB color componenD^ of all plxti^) 
between the desired mige and ilx" mosaic image, atxl speed. 

StiUiUon Stmtegy 


There is a iradeHjflf between aehievalTle etdor diaance and speed Ihe number of 
tk^grecs of freedom given - elwice of tile size above a minimum, position of the 
tile cut from die chosen element ■ Ls too Large to :tllow for an exhaustive search 
of all possible tile cuts C'clcment slkxs'^ Rir Jtll possible Hie sto. 

I select the two smallest tile sizes tli;it can be used u> fill tlie mosuc. 

Each dement, as well as the files to be miitchtxl, are nrpresenuxl as an array of 
"Spots", a spot being a 4 by 4 duster of pixds. 

In a next step, ail possilie slices of the elements are Jissigned a luminance value, 
and the slice is stored in an arraj <if lists, the being indexed liy lummance 

To match a desired image dten, each tile of tlx^ mosaic is pnxessexl imkpendently 
Tire luminance of tlie file (in the tlesired picnife) is useti as an index into the 
siiee The ptJsiiion in the slice amiv' will lx* in tire* miter of a nmge of 
Sikes of similar luminance res tlx fik to lx* matched. 


// Galled <jn.ee to initialize the dements in a new Mosaic dass. 

// Mosaic dement images are pkeHocked in InitMosaic, and remain kxked 
// imtil TermMosaict) is called. 

i 

assert (gM=0) t 

gM=nsv/ Ernst::MosaiG(element.mimMosalcs): 

f 


const PixMapHnndle deelredlmage, 

/* PixMapHamllc populated with tlx^ desired image t<j be constructed V 
const Rect minPieceSize, 

/* mosak pieces must be of this size or larger V 
PixMnpHandle mosaic, 

f PixMapHantllc to preallocattd image in whidi die mosaic is to be placed 7 
r liiitiaiized to bhek V 
MosaicPiece "piece. 

r pointer to array of mt^wak pieces V 
r popukied b)^ your code 7 
long "nuniMos^ePiBcas 

G number of mtJsfic jdeces created by j'^iur code 7 

// May be calkd multi|ile times with different desiredlmages. 

// !ind possibl)' w^ith a dilTcrem minPiect’JiiZf. 

//The function kxks/unlocks tlxr image pixels, 

//Tltc mtXiak' is prepared (a private set of image piumueters of the tksired image), 

// solved (element slices assigned to ntosak tile ctxjrdinales) 

// and cleiiixd up (the pmaie set dekled). 

I 

LockPixels(desiredImage): 

LDckPixels(tnoGaic); 

"numMoeaicPieces = 

->PrepareMosalc(desiredImage.minPleceSize); 


In the next step, all slkes within the indicated range are amipared (KMIS color 
distance) with tlx tile, and die closest slice itkniificd. 

I Ip to iliis jjoint, only slices on the bpixel grid were consklerexl. lire- closest 
klendfied slice is then taken as tlx* center of a small :irea witliin the clement. 
and slices on a I pbcel grid are evtinated to make the final selectkin. 

Tlie metliod to control nuining time Is to dxiose the size <jf the range* uf slices 
within the slice array that are e^-alnated. 

Since the running time penalty 1% per second is ^ixed^bu^ running lime is roughly 
pnjportioiial to image size, the rangji* is cho.scn as die rci:ipnx''.il of tlx image size 
times an aibiiraiy* facltirio yield alxjut a 1(1 to 20 'Kj penalty on a largic (i-3Mpixel) 
image. 

Vector Processor 


ITx processor in tite G4 Macs contains a vec tor prexx’ssing unit (Mtivee), Ibis 
processor is very effickni at pnxexsing up to 16 bytes in |Xirallel, just Ox 
thing to process pixels in parailel.as long res the pixels are represented 
in phnar form. For example 3 vectors can Itold 16 pixels (16 hvtes of tlx same 
color in each vector). An RGB repre-scntaiion (324iil pixels) of a S[X>1, containing 
4 by 4 pixels of an image, nan lx eirieienUy converted into a plareir vector 
represcniation. 


gM->SolveMosflie(mosaic.piece )i 

gW->Clennup(); 

UniockPixels(mosaic); 
UnlockPixel^(tlesiredlmage): 


void TermMosalc(void) 

r deallocate any menx>r)' alkxuted by InitMosak or multi|>k Mo&fic calls 7 


TermM<lsaic 


delete gM; 
gM=0^ 


MosaicClasses-v2.h 

#ifndef HOSAIC_CtASSES_ti 
((define HOSAIC_CLASSES„H 

r 

"Plxao Mosaic" 

Version 2: 


This tlxn alk>ws tlx RMS color dilference of sets of 16 pixels to lx- computed 
with a very* small numtxr of instrueiions. 

1 use an approximation of the true RMS vahx, by ;idding the largest alis<diite 
diflctcixes betwifcn eorres|Xinding pixel pkines (R/ior B) to 3/16 of the sim of 
tlx Edisolutc differences of tlx other pL'ines, 

Tliis is the most busy liirxtion. of the algoiitlmi; it l:ike,s 23 vector iiisimctioiis 
to amiputc dx sum of die RMS color difference of 16 pixel pairs. 

Version 2 changes are* described in "Mosaic(lresse!irv2.h". 

7 

#include "Mosaic,h" 

^include "MosaicClasses^vS.h" 

static Ernst::Mosaic" gM;// Mr>sak classi'Sone in mmespaec Ernst 


Simplification in luminsijxx' rciric*val: 

crest return V4due directly from nxmoty to un.signed bug. 

In MatidilikO: 

Try tlx best slkre from the pre*vit>us tile finii, 

Altermtive sclxme (SGIIEME ^ 2) atlded: 

1)0 preliminaty imiidi on die avenigt* color of each spoi, 
instead of on the iixlividUiil pixels of the s^xil. 

Ibis provkies a signtficanl .speedup, at the exjxnse of 
sliglidy higtier overall distances, resulting in similar scores. 

'Ihe original scheme I is predtmxl bt^caiese it producer a sllgttdy bener 
match {kSe“iretvR;iiigcr“iclor set l(j optimize for a l% / sec time penalty*)- 
7 

#define NDEEllG 
^Include <cassort> 

#includo <cstrlng> 


InitMosaic 

void InitMosaic( 
short numMosaics. 

/* number of pixmaps from winch the mosaic should be created 7 
const PixMnpHandle element[] 

r elemenrli] is a PixMapHandk to the kh image used in constructing mosaic V 


#deflne SCHEME I 

//A namcspxc is ereaied to avoid name dashes with Apple headers cjr test code 
namespace Ernst I 

typedef unsigned char uchar; 
typedef unsigned short ushort: 
typedef unsigned long ulongt 
typedef ulong Pixel; 
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vMaK=vec_iiiax(vMax»dBlue): 


typedef vector unsigned char vuchar; 
typcdef vector unsigned short vushortj 
typedef vector signed long vlong: 
typedef vector unsigned long vulong: 
typedef vector bool char vboolchar; 

// Micjios cxtnKX the lui gi^^citaiui blue components of a 32-bii RBG pixel 

iMefine mRED (pixel) tOxFF & ((pixel)^M6)) 

#deflne mGREEN (pixel) (OxFF & ((pixel )»S)) 

ffdeflna mBLUE(pixel) (DxF? £i (pixel)) 

enum I 

kSpotSize^ 4. //4 by 4 pixels 

kSpotHelght = kSpotSize, 
kSpotVidth = kSpotSize, 

kNutiLunilnanceLevels = 1+255 * 3 , // sum of R4 <j+B ranges fnim 0 to 755 
kSearchKangeFactor = 1000*1000*1000 //dx^sen m ykld reasonable 


//Vecitir function^ computes the absolute difference between all pairs of 
// the vectoT’Cfements in a atxl b <T is an unsignciJ wxUrr type) 
template <dassT> itiiineTAbs[>iffe[ena<r iT b) 

[ 

T iiiax=vGC„niax(a,b); 

T niln=vecjniti(a,b): 
return vec_Bub(max*iinn): 
f 

//Wttor ftmctk>ns^ computes an estimate of the RMS sum t)f the color 
// differeiK^ of all pairs of adiir pbnes 1 (vrK^-givbl) and 2 (vr2,\-B2,vl>2) 

//llie algorithm h 

if max = ihe largest among die components R* and B 
// minA and minb are the odKT twtj eom|xint*nts 

// RMS -'= max + (minA+nriinB)*5/ i 6 
if Returns the sum of the sixteen RMS distances so computed 
inline void VColorlHetanceC 
vuchar vrl* 
vuchar vgl, 
vuchar vbl, 
vuchsr vr2. 
vudiar vg2, 
vuchar vb2* 
long* result) 

I 

vuchar dRed==AbsDifferencG<vuchar>(vrl.vr2): 
vuchar dGreen“AbaDiffer0nce<vuchar>{vgl*vg2): 
vuchar dBlue^AbsDifference<vuchar>(vbl♦vb2); 

vuchar vMax=vec_niax (dRed * dGreen ); 
vuchar vMiiiA^ec_niin (dKed»dGrecu]: 
vuchar vHinB=vec_ndn(vMax,dBlue}; 
vMax=vec_inax (vMax. dBlue): 

vulong k4^(vulong}(4t4H4»4); 

vuchar k5=(vuchar) {5 5 h5J.5, 5,5.5.5< 5,5*5*5); 

vulong kO"{vulong)(0,0*0*0); 

vulong pa ci:Suid^ax=vGC_sui]i4s (vMax. kO): 

vlong suaMax=vec_suj]is( (vlong) partSumMax* (vlong)kO): 

vulong i nt e rraedia t eMnA^vec _ros um (vKi nA * k5. kO); // *5 
vulong intennediatGKinB=vec_msu!n (vKinB * k5 . kO) •// *5 
int ertnedlat eMinA=vec_add(lute tmediat sMinA *int e nnedia t eMinB): 

intennediateHinA=vec_sr(inteniiedlatettlnA*k4) :///lb 

vlong suifl^vec^sums((vlong)intermediateMinA.sumMax); 
EUtii^ec_splat(suTa*3): 

vec_Ste{suni0,result); 

1 

inline void VColorDistanceLong(vulong vl*vulong v2.1ong* result) 

I 

vulong delta=AbsDiffGrGiice<vulong>(vl* v2): 
vulong dRed =vec_Eplat(delta * 1); 
vulong dGreen^ec_splat{delta*2): 
vulong dBlue=vec_splat(delta.3); 

vu io n g vMax=ve c_tiiax (dRed, dGr e en): 
vulong vMlnA=vec_niinCdRed.dGrGGn): 
vulong vMinB=vec_i!d.n (vMax. dBlue); 


vulong k4=(vulong)(4,4 * 4 * 4); 

vushort k5=tvushort){5.5*5.5. 5.5*5*5); 

vulong k(}=(vulong) (0 * 0 * 0 * 0); 

vulon g suiB=ve c_ad d (vMl nA. vMin B) i 
s uiD=vec_i!isum {{vusho r t) sum * k5. kO); if *5 
siaii=vec_sr (stim*k4): if /16 

Buni=VGC_add(sum*vMax); 

vec_ste ((vlong) sum * 0 * result); 

1 

ttesSpoi 

//fim/m/f/miii///fimfm^^^^^ 

if 

//A Spot represents a square of 4 b) 4 pixels, 

//This is the smallest screen element representabk 
// as a set of veaurs. eadi vector in a different txjkMr phne 
if a>lof planes are R, G. fl, and alpha, 

//The alpha values (x) ate igmmxl. 
if 

/////////////////////////////M^^^ 

claaa Spot 

I 

vuchar xrgbLkSpotSize]; 
public: 

void lult(Pixel* pixels,int rowPitch) 
if Itiiiializes a ftdl spot of 16 pixels and tximputes spot luminance. 

//’Wt copy ilie 16 pixels into vectors, 

// using memepy heeaujic the original pixeb may not be I6byte aligned 

f 

for {int i=t);i<kSpotSixe;l++*pixelsi=rowPttch) 

Btd; tntemcpyCxrgb-H .pixels,sizeoflvuchar)); 

MakeColorPlanesO: 

} 

ulong ColorDistance (Spot£i S) 

//Wrapper for the inline vector hmeiion VtkilorDistanceO 

I 

long result; 

VColorDistance( 

xrgbfl] .xrgb [2j *xrgb[3l * 

S.xrgbllJ,S,xrgb[2],S,xtgfal3], 

^result); 
return result; 

I 


ulong ColorDistanceLong(Spor5i S) 

// Wrapper for the inline vector funetkjo Vt ’jokirlhsumceLongO 
1 

long result: 

VGo lo r Di e t a nc eLon g [ 

(vulong)(xrgb[0]), 

(vulong)(S*xrgb(0]). 

^tGEult); 
return resulti 

1 

ulon g Lumina n c e() eons t 
// Renims the spot luminarKt suirfd ai 

I 

return *((ulong*1(xrghj); 


private; 

void MakBColorPlanesO 

//TransfiJnm 4 rows of 4 pixels each Into 3 etjlor phnes and a lumimmcc plane, 

// Uses vector operations to efficicfitlv nKwe the 16 R,Ci,B pixel valiKS areiund, 

I 

vuchar vXRGBO^xrgbtOl; 
vuchar vXfiGBl=xrgh [1]: 
vuchar vXRGB2=xrgb[Z]; 
vuchar vXRGB3=xrgb[1]: 

vucha r vRB 01 ^ec_pac k {(vushort) vXRGBO, (vushor t J vXRGB 1): 

//extract RIJ 

vuchar vRB21=vec_pack{(vushort)vXRGB2 *(vushort)vXRGB3): 

vuchar k8=(vuchar)(S*8*8*8*8*8*B,S*S*B.8.8,3*8*6,83; 
vuchar v0XRG0=vec_sro(vXRGB0*k8): //sliUt riglu 
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vuchar vDXRGl=vec:_flro(vXRGBl ^kS); 
vnchar vOXRG2=^ec_s ro (vXRGB2 , k8): 
vuchar vOXRG3=vec_sro(vXRGB3 .k3}: 

vuchar vXGOl=vec_pack ((vushort) vQXRGO, (miahort) vOXRGl); 

//ettradXG 

vucha r vXG2 3=vec_patk ((vusho rt J v03®G2, {viishor t) VOXRG3): 


vuchar vB=vec_pa[ik[ (vushort) vRBOl, {vushort) vRB23): 

//GctiaciB 

xr gb [3] =vB: // store B 

vuchar vG^ec_pack((vushort)vXG01, (vtishort)vXG23) i 

// estraa G 

Krgb[2]=vG: //slokQ 

vuchar vOROl“vec:_sro[vRB01 ik8): //shift right 

vuchar vOR23=vec„sro(vRB23.kS); 

vuchar vR=vecjack{ {vushort)v0R01, {vushort)vOR23): 

//extract R 

xrgbtlJ^Rj //store R 

//Add all R G B components to obtain the sptJt luminance; 
vulong kO=(vulong)( 0 , 0 , 0,05 ; 
vulong sumB = vec_si4Jii4s(vB,k03: 
vulong suniG “ vec_sumAs{vG,kO): 
vulong audR vec_suni4fi (vR^kO); 
vulong suiiiBG= vec_add (suraB. sunifi): 
vulong su[nRBG^ec_add ( bumBG , sumR) j 
vlong Irgb = vec_suins( (vlong) suroRBG, (vlang)kO): 

#if SCHEME=-2 

// Compute the individual RCiB sums ( = average a^Ior cif a spot) 

// liidJ = luminancxMUilgjeeti, blue 

Irgh “ vec_Bld((vulong)Irgb.kO.121: 

smi]R (vulong)vsc_sums( (vlong)sumR. (vlong) kO): 

sumR = vec_sld(sujiiR.k0.8) J 

suraG “ {vulong)vec_suins ((vlong) sumG, (vlong)kO); 
sumG = vec_sld(EuiitG*kO,4); 

sumB = (vulong) vec_suina ((vlong) suitiB. (vlong) kO): 

Irgb ^ vector (Irgb, aumR}; 

Irgb “ vec_oc(lrgb*BuinB): 

Irgb = vec_or{lrgb*suniG); 

#else 

// Splat luminance into all 4 words 
// ligh - luminance only 

Irgb ^ vec_splat(lrgb,3): 

#endif 

xr gb [ 0 ] ” (vuchar) 1 rgb: // sttxe luminance (and RtiB in SQ lEME 2) 

I 


stnjct Slice 

// 

ifh Slice is an ekmem in a singly linked list. 

//A slke identifies a slice (of arhitrarv^ dimensk jn) in an ekmeni 
// by’ its top left c’tjmcr. 

// 

////////////////////////////////////M///////////M///////////////////////////// 

struct Slice 

{ 

Slice* next; 
abort eleinentld; 
uchar top; 
uchar left: 

Slice [) :next(0) . elenientld(O), top(O) . left(O) \ I 
Slice{SIice* s.long id,long t,long 1); 
next(s), 
elementld(id). 
topCt). 
left(l) 

II 

I: 

typedef Slice* SlicePtr; 

daiei Image 

mmiimmmmmuimiiimiimmimimmmm 

// 

// An bmge is represented by a reference Ui die origmal <52-bii) RGB pixels 
//ITie pixels omy^ converted into a representation as spots, 

// AB elements, the desired image, die mosaic, and the ciurent iifc,are 


// represented by an image structure 

// 

//Wlien used Ibr elements and the eurrem hie, spots are allocated (planar copies 
// of the pixeb), and coriespondir^ data members initialized and uid. 

// 

class Image 

f 

Pixel * pixels: // pixel pointer to originaJ pixels 

Spot* s pot s: // spots are; alkxuted for elements and files 

bool allocedPixels; 
bool allocedSpots: 

short width; // widfii of the image in pixels 

short height; 

sho rt rovP itch: // ruwBytes / 4 

Ion g elemen t Id: // needed when element is copied to a mosaic piece 

long numSpots: // spots related dimenskms 

short uumSpotsH; //horizontU 

short numSpotsV; //vertical 

public: 

// Ira^ Constmaors 
Image 0; 

pixels(0),spots(0)* 

allocedPixels[false)* allocedSpots(false) 

(I 

Image(Pixel* c_pixela. 

Spot* c_epots* 
bool c_anocPixels, 
bool c„allocSpats, 
long c_Width, 
long c_M&ight, 
long c_RowPitch, 
long id): 
pixels(c_pixels). 
spotsCo_spots), 
allocedPixels{c_allocPixelE3 * 
allocedSpDts(c_allocSpots), 
width(c_Width3* 
height(c_Helght3, 
rowPicch(c_RowPltch}. 
elementId(id) 

II 

// intiBC JkstrueUir 
-ImageO 

I 

if (allocedSpots && spots) delete H spots; 
if (allocedFixels pixels) delete [] pixels; 

) 

// Image accc^M^ fiinctkms 

long WidthO const I return width;] 
long Height(3 const !return height;] 
ulong* Pixels(Int row,int col) const 

I 

return pixels+col+row* rowPitch; 

) 

long RowPitchO const I return rowPitch ;! 


void Init(const PixHapHandle pm.long id) 

// Inilialiycs an Ima^' from a QuickDraw PixMtpHandIc 
[ 

pixels=(Plxel•)GetPixBaseAddr(pm); 
al10cedPixe1s=fa1se; 
allocedSpots^al se; 

width=(**pm) .bounds, right- (**pni3 /bounds,left; 
hei gbt=( * * pm). bounds * bottom- (* * pm), bounds. top; 
rowPitch=(0x3FrF fe (**pni). rovBytes)/eizeof (Pixel): 
elementld^id; 
spots^O; 

1 

//11pdalc FiitKlkma diangc five image information for a previously inifiaHzcd 
// Saves ddciing/reounstniciing micccssivc stja-s or files during the seareh, 
void Update(Pixel* c_pixels.long c_Width,long c_Height3 
I 

pixels=G_pixels: 
wldth=c_Width; 
heighr^c_Reight; 

1 
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void Update(Pixel* c_pixelsl 

I 

pixels^c_plxeIsi 

I 

void AllocateSpots() 

// GmipuccJi number of sp(3Ls^and allocates new spcjLs for die imagp. 

[ 

ntDiiSpcitflH=vidtli/k3potWidth; 
numSpo t s V=h eig,ht/kSpotHe± ght: 
nuioS pot s=numSp ot s H numSpot s V: 
spots “ new Spot [numSpots]: 
allocedSpotfi=^ruG; 

I 

Spot * ItiitSpots {) 

//Allocatci spiJts if nt%:essary, 

// Iniiialto the .spoL-i ix\ a 4-pixd grid (^patTOth=kSpotHdght=4). 

// If tmagp width or hei^t art not mntiiples of ftntn pixels 
// along the bonom and right edges are not repiescntcd in spoLs, 

// Kemms die (pcKisibI)- ik'W'Iv aDocared) spots. 

[ 

If (!spots) AllocateSpots[}: 

nmESpotsH"width/kSpottfidth: 
nuinSpotsH=he±ght /kSpotHeight: 

Spot^ SP=3pots-lj 
Pixel'" pRow^pixels; 

Pixel* pCol=pRow: 
long col; 

for tint row^: tow<numSpot3V; roi*H-s-) 

! 

for (col^: coKnumSpotsE; col-PH. pCol+=kSpotWldth) 
I 

(++SPj ’ >Iiiit (pCol .rowPitch): 

1 

pRowf^kSpotHeight * rowPltch; 
pCol^-Row: 

] 

return spots: 


sum /= tileRangeV*tileRangeH*kSpotSlze*kSpotSizG; 
assert fsuni<kMuinLiiniliianceLevels); 
return sum: 


long TileLtnninanceO 

// Returns a nonmted sum of lumtnance valnea of a tiJe. 

1 

long 1utD=Slic eLuminance(0,0,numS p o t sH t nnmSpot sV): 
return lum; 


ulong EawDistance(Slice* slice,ImageSi tile,ulong mlnDistance] 
// CkxnptJles tile raw color distajue between a slice in an element^and die image tik\ 

// Brea^ computation off early If (pit.™mly finimi) minimum distance is exceeded. 

// Kciuins the acaimiilated color distance. 

I 

long bottoai=slice * >top /4+tlle. nuinSpotsV; 
long right=slice->left/4+tile.nuinSpotsH: 

Spot * e 1 emen t Spot=spot s+s lice-) top / 4 * nuemSp o t eH ; 

Spot* HleSpot=tile*spots: 
ulong dlff=0: 

for (long row=slicG->top/4:row<bottoTn:rowf+) 

i 

for (long col=El±ce->left/4;col<right:col-H-) 

[ 

/fif SCIIEME=2 

Long d=elementSpot[col].ColorDistanceLong(tileSpot[0]): 

//else 

long d^lement Spot [col] XolorMstance{tlle3pot [0]): 

tfendif 

dlff-H=d: 

if Cdiff>rtiiiiDistance) 
return dlff: 
tileSpot+'i'; 

1 

elementSpot-l-^umSpotsH; 

1 

return diff; 


ulong ColorDistance(Itnage£i tile) 


long PrepareSlicesfSlice** sliceindex.long tileRangeH, 

long tileRangeV) 

// For each ptjssihic slice in an ekmentp computes slice luminance and 
// attaches the slice to a list in sJk:e!ndex[lumiiiance], 
if Returns the number of slices. 

I 

assert{spots) ; 

long spotRangeH=tiiiiiiSpotsH-1i 1 eRangsH; 
long spotRangeV=numSpot eV- 1i1eRangeV: 
for (long spotRow^O:spotRow<spotRangGV:spotRowif) 

for (long spotGol=0;apotCol<spotR3ngeH;spotCol-H-) 

I 

ulong luminance^ 

SliceLuaiina.nce(spotRow,spotCol. tileRangeH*tileRangeV); 
assert (luminance ^ kNutuLumlnanceLevelE): 

Slice* newElice=new 
Slice{siicelndex[luminance],elementId, 

4*spotRow.4*spotGol}; 
sliceindex [luininance]=newSlice: 

I 

] 

r Gtum s p otRangeV * s potRangeH: 

1 


long SllceLuminancedong spotRow.long spotCol, 

long tiieRangeH.long tileRangeV) 
// Returns a nf>rmalized sum of luminance values of a tile or slice. 

t 

Spot* S'="s p ot E+s potCo 1+sp otRow * numS pot sH ; 
ulong sum=0: 

for (1 ong r-O r r<t ileRart geV: r^] 

1 

for (long c^;c<tileRHngeH;c++) 

f 

ulong lu=S[c],Luminance(}: 
sum+^lu: 

I 

St-numSpotsH: 

) 
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cbss Mosaic 


//The smu: pitrpose as Iniagie-KawDistance, but used wlien the class instance of 
// the imge Ls a custom mpy of a slice (on a l-pixd grid) 

//Tills avoids having to deal with imahgned sptits. 

( 

assert(spots): 
assert(tile.spots): 
assert (tium3pots=tile h numSpots): 
ulong diff=0: 

for Cint 1=0 :l<rLumSpots ji-H-) 


//////////////////////////////////y/////////M^^^ 

// 


// TTie class Mosaic is initiali/ed by InitMosaicO ^d ttesm>ycd inTemiMosaieO. 
// it [jumdes the tmks to the dements, builds tiles as requlmd, 

// and matches die dement slices to die desired images). 

// 

mmimimuimmmimumimiimiiiummiimmiimimmi 


class Mosaic 


long d=spcits [i], CalorDistance (tile. spots [1]); 
diff+=d; 

I 

return diff; 


ulong HatchVlcinity(Slicei slice.Imaged tile) 

// After hiiving fesimd a g(M>d candidate slice, tlds hioction Is used to miat>aligii 
// the slice on a I -pixel grid, in order to f titain a pt^il% better match. 

//A pixel vicinity of the original slice position is explored, 

f ' 

enun IDELTA=3I: 

ulong mlnDistance^OxEFEFFFFF; 

int r0=slice,top'DELTA:if (r0<0) r0=0: 

int c0=slice.left-DELTA:if (c0(0) c0“0: 

int rl“^slice. top+DELTA; 

if (rlHheight-tile,height) rl=height-tlle,height: 
int cl^slice,left+DELTA: 

if (cl>=width-tile*width) cl=width-tile *width; 

Image sliceltnage 

(Pixels{rO,cO),0,0,0,tile*width,tile,height.rowPitch,0); 
for (int row"r0:row<rl;row+f) 
f 

for {int co1=c0:cd1<c1:co1+-h] 

] 

slicelmage,Update(Pixels(tow,col))i 
eiiceTmage *InltSpots(): 

ulong colorDiBtance=siiceTn»age,ColorDiatance(tiie): 
if (colorDlstancG<iiiinDistance) 

[ 

minDistance=.coi or Distance; 
s1ice.top=row: 
slice,left=col; 

1 

[ 

I 

return mlnDistance: 


void CopyToPieceC 

MosaicPiece& piece,int top,int left, 
int pieceWidth.int pieceHeight, 
int 3liceTop,int sliceLeft) 

// Q>pies the pbteb idcntilled by a slice in an ckmeiit.to a MosaicPtcce. 
f 

piece,elementIndex=elementId: 

Rect elemetitRect^lsUceTop,sliceLeft,sllceTop-l-pieceHelght. 

sliceLeft+pieceWidth1: 
piece, eleinentRect=eleEnentRect: 

Rect inosalcRect“{top,left,top+pieceHeight,left+pieceWidthl: 
piec e. mosa iGRect=it]osaicRect: 

> 

void CopySlice[Imaged E, 
int top,int left. 

int pieceWidth,int pieceHeight.long sliceTop.long sliceLeft) 
// Ciipics die pixels identified bv a slice in an clcincni, into the mosiiic image^ 

[ 

int srcRciw=sllceTop, srcCol=sliceLeft: //11ci>mer of slice 
Pixel' src=E. Pixels(srcRow,srcCol)://slice pixels 
Pixel ‘ dest=plxel sf left+top' rowPitch// mosaic pixds 
for (int row=0;row<pieceHeight:rowti) 
f 

for (int col=0;col<pieceWidth:cal-H’) 

[ 

dest[coll^src [col] ; 

1 

src+=E-rowPitch: 
dest+^rowPitch: 


//The fblRjwing data memlx^rs are defined when InitMiisaieO funcQon runs 
const PlxMapHandle* element: 
long numElements: 

Image el ement Image s: 


//'llie following data members vary with Live inLigc and are tlefined when MosaieQ 
// flmctk>n nms 

Slice** sliceindex: //Arrty of linked lists of slices 


Image* desiredlmage: //the desirecl image to Ix^ matebed 

short ImageWidth: 
short imageHeight; 


short ti 1 eWidth: // mtn tile wldiii comptiWc with desired image 

short tileHeight: // min tile hciglit compiitible with desired image 

short tileRangeH; // tile width in temis of spots 

short tileRangeV; // tile heiglit in terms of spots 

1 ong numTl 1 eCo 1 sN ar r ow: // niindxr of narrow colmims of tdes of tilcWidUi 

long nutnTl 1 eCoIs; // totai iiumbcT of tile columns (nanow -i- wide) 

long numTi 1 eRowsShort; // niimbt'c of shon rows of tiles of tlkHeight 

long numTileRows; // total numlxf iif tile rows (shirt + tai) 

long nrnnTlies; // = numlxr of mosaic pieces 

long searchRange: // v:tliic contollktg extent of seiiidi in slicelndex 

short previousTi 1 eRangcH: // if successive c'.ilfs to MosaicO result in ideniieal 

short p reviousTileRangeV: // lileRanges, we can avoid some recompurations. 


public: 

//An iasianee of djea Masaie is constructed wiiil tlic clement images to be used later. 

Mosaic (const PlxMapHandle c_eleiiient [ ] .long c.^numElements) : 
element(c.element)» 
numFJenients[c_nuiiiElsmetits), 
element Images (new IiiiageIc_nuiiiElements]), 
sliceIndex(0), 
deslredlmage(O), 
searchRang&(0), 
previousTileRangeH(0], 
prevlousTi1eRan geV(0) 

I 

for fint i=0:i<nuniElements:i++) 

I 

LockPixeIs ( elctnen 111 ] J ; // element pixels locked in eonstnictor 

eiaiDGEt Images [1], In it (element [i] .1): 
elementImages Li],InitSpots(): 
f 

] 


// Oe^^nietor nirLS when TermMosjiic b culkxl 
^Mosaic() 
j 

for (int i-0:i<numEleiaents:i++) 

( 

UnlockPixels (element [t]): // element pixels mikickcd in destructor 
I 

if (desiredImage) delete desitedlmage: 

DeleteSliceIndexO ; 

if (elementImages) delete [] elernentlmages; 

] 

long PrepatEHosaic(const PixHapHandle c_desiredlmage, 
const Rect c^minPieceSize) 

// Cilled from MiMiaic(),tti pn:[Xire th- image and ih ckments for the search 
// (iKKises a (initi;il) scardi riipge, to aehiew iea.sortaNe quality !ind run time. 

//Tile plan wis to update this number [>eriodic;iliy as tlie sciiah progresses OHD). 

// Rentms live niimher of Ub; thu will Ix^ used to constmei the mosjJc. 

I 

PrepareDesired Image (c_desi red Image ,c_iiiinPieceSize) 3 
PrepareElements(J ; 

ChooseTnitialSearehRangeO; 
return numTiles; 

1 

double SolveMosaic(PixMapHandle mosaic.MosaicPiece *piece) 
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// \^di tile of the mosaic is mdepeiKleritly diosen, aJler comjxiriso[n with the 
// selected mngp of candidate dices. 

I 

Pixel‘ P=desiredInage->Pixels(0.0): 
long rowPitch=desiredImage->EowPltcli{); 

Pixel * iiiosaicP= [Pixel *) GetPixEaseAdd r {mosaic): 
assert(mosaic?): 
long mosaicRo¥Pitch= 

(0x3FFF & ‘mosaic).rowBytes)/siseof(Pixel): 

assert (niOEaicRowPitch"=desiredlmage->RowPitch()); 

Image mosalcimage; 

mosaicimage,Init[mosaic.0); 

long pixelRow=0; 

long pieceHeight: 

// pnedlocatc Im^gest tik 

Image tileToKatch(0.0,0,0 * tileWidth+1.tileHeight+l* 
rowPitch*-1001}: 
tileToMatch.AllocateSpots [): 

Slice bestSlice; 

SlicePtr sliceP=0: 


for (long tileRow=0: tileRow^numTileRowa: 

tileRo’ifl+, pixelRoi*r+=p ieceHeight ] 


I 


long plxelCol^: 

pieceHeight=(tileRowCniiJiiTileRowsShort) ?tllelieight: tileHeight+1; 


long pieceUidth: 

for [long tileCol^O: tlleCol^-tiumTileCols: 

til eCo 1 ++. p ixel Co l^p i ec eW i dth) 

I 

pieceWidth= 

[tileCoKnumTlleColsNarrow) ?tileWidth: tileWidth+1: 
tileToMat ch.Up d a t e(P+pixeiCol+pixelRow‘rowFit ch.pie c eWidth. 
pieceHeight): 
tlleToMatch.lrutSpoteO : 


//Ihc cxll to MaLchTde, once per mosaic pkte.tthtxjns die liest notching slice on 
// the d-jibcei grid. 

MatchTileCtileToHatch.iisliceP): 
assert(sliceP): 


I 

S1ic e‘ next Side e=S■> next: 
delete S: 

S=nextSlice: 

I 

J 

delete [] sliceindex: 

) 

long FlndTlleSizeCiong Xtlong t.longSi n,long& m) 
// Solves die diophaiitiiK' etiuatkin’ n*t ni'Otf) = x. 

// X = image size (width or lidghOr 
// t = initially the n±iimum tile jaze, 

// Hclii n (niunber of tiks size t) and m (munber tif size l+l), 

//ITiis fiinciion is ivsehil in finding die smsdlest [KMsible tile dimensions, 
// tbit are comjxidbk with the image diiiieiisions, 

//llie xssttmption is diat smaller tiles pnjvide bciier matches 
// Returns t which may have been increased fimi die initial value. 

[ 

for (::] 

[ 

n=x/t; 
tiiP=x * n ‘ t: 

n^(x-m*(t+1))/ti 
if [n>=0) 
break: 
t-H-: 

I 

return t; 


void Preparebesiredljnage(const PixMapHandle c_desiredlmage, 
const Rect c_niinPiEceSize) 

//AruiJ^'Ses die dimeiisioas of die desired image, and minl^eceSi/^, 

// :ind determines tiling cijnsiants. 

// l^ftemiines die total nimil>eri if mosaic pietx'.s neetkd (mimTiles). 

I 

dead red l]nage=riew Image: 

desiredImage->Init[c_desiredImage >-1): 

const Rect& iBounds=(**c_desiredImage).bounds: 
L!nflgeWidth=lBovmds, right iBotinds. left; 

ImageHeight-iBounda,bottom-iBounds.top; 


// Stitrting frcjtn the slice on the i-pixel grid, MatchVkinity sons tlx" neighborhoexj 
// (if ibis slice in an effort to uhLtin die "best slice". 
bestsllce=‘slice?: 

elementImages[bestSlice.eiementld].MatchViclnlty(bestslice* 

tileToMatch); 

//'File Ix:fh sdkx is copied into die next MosiicPk.'ce stnictiine, 

elementimages[bestSlice.eiementld).CopyToPiece( 
*plece++.pixelRoWt plxelCol. 
piec eWidth.pieceheight. 
bestSlioe.top.bestSlice.left): 


tileWidth^c_miriPieceSi 2 e, right -c_[iilnPleceSize. left; 
tileHelght-c^minPleceSize.bottom-c^minPieceSise.top: 

long numTlleColsLong: 

tileWtdth=FindTileSiKe(imageWidth.tileWidth. 

numTi1e Co1s Na r r ow.numTileCoisLong): 
niimTl1eGols^numTileColsNar row4nuraTileColsLong: 

long numTi1eRowsLong: 

tildielght"FindTileSixe(imagoHeight.tlleHeight. 

numTileRowsShort.numTileRowshong): 
ntimT i 1 e R ows^] umTi 1 eRows Shor t+numT i 1 eRowsLori g: 


//... :uid co|>kd into rhe mosak, 

mosaicimage,Copy$licE( 

elementimages[bestSlice.eiementld]t 
pixelRow.pixelColppieceWidth.pieceHeight. 
bestSlice.top.bestSlice.left); 

I 

) 

return 0; 


void Cleanup() 

// Clonup Ls needed after och dcsiitd iniagp lias litcii miidc into a mosaic, to ddcic ii. 

[ 

delete desiredImage: 
desitedlmage=0: 


private; 

void DeleteSliceIndexO 

// DcktcSliccIndcx contains a loop to delete all indivkluall>' allocated slices. 

[ 

if {Isliceindex) return; 

for (int i=0: i<kNnml iiim1 nanceLevels: i+-t) 

[ 

Slice* 3=sliceIrLdex[i]: 
while (S) 


tileRangeH=tiloWldth/kSpotWidth: 
tileRa n goV=t 11e Height/kS p ot He!ght: 

numTi1es =numTileCols‘n u mT11eR ows : 


void PrepateElements() 

// Ifsing tile iiize informatkm. prepares Lhe slice inventor) based on anrage 
// kiminance. 

// If tile size has noi dtmged from the pre\'kHis image, there Is no need to redo tiiis. 


if [(tileRangeH 

previousTileRangeV)) 
return: 


previousTileRangeH) && 
(tileRangeV = 


p r eui 01 ] s Ti 1 eRa n g eH===t il eRan geH: 
p r evious Ti1eRan g eV=ti1eRan geV: 

if (sliceindex) DeleteSlicelndexO: 
slicelndex=new SlicePtr[UNurnLuminanceLeveIs]: 
std::memset(sliceindex,0. 

kNumLumiiian,ceLevels‘sizeof (SlicePtr)): 
for (int i=0:l<num£lements:i-H-) 

( 
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elementImages[1]. 

Prepare.Slices(slicelndex, tlleRangeH, tileRangeV]: 

I 

I 

void ChooselnitialSearchRangeO 
//A simple attwnpt to de&ie a seardi range titit will ght' a j^ood matdi^ 

// without niruiiug unreasonjibly long. 

I 

long imageSize=desiredImage-)Width()^desiredImage-)Height(): 
sea r chRan ge=kS ea t c hRangeF actor/ ittia ge S i z e; 

I 

ulong MatchTile(Images tileToMatcii.SlicePtr* hestSliceP} 

// Function MairhTilc ntJUdKs the tile against aJI .slkxs svirhin the seaiidi rapgp. 

// h sums in die slice inventor}^ widi slices of the same himinance as die tile. 

//Tlieti slices of liighef and lower iLiminance iite considered, until the seatdi ranter 
// is exhaiKled. 

// For each slkc, the color distamo its the tile is determined 

// the snuiUest disumce is retained as minDLstancot Ujgctlier widi bcsuSliLOp 

// Returns the minimum distance, and a pobter to the best slice in the bvetor). 

I 

long tileLuiiiinance“tileToMatch.TileLuininanca() : 
assert (tileLmiiinanca<fcNumLiJiiiinanceLevala}; 
assert{slicelndex)■ 

ulong mlnDiEtanceHlKFFETFFFE'; 

if {* be s t S lie e P) //cry previons btvst sike Bna to bendimark minDistance. 

[ 

tiiiiil]iatance= 

elementlmages((‘bestSliceP)->elementId]. 

RawDlstanc e(*bestSlic eP,tileToMatch,minDistance)i 


int leftToCheck=searchRange/2: 

for (int i=tileLuniinance;i<kNuiELumlnanceLevelsti-H-) 

f 

leftToCheck=MatchSliceList( 

sliceTndexU]. tileToMatch* *bestSliceP, 
mitiDistance,leftToCheok); 
if (leftToCheck<^) break r 


leftToCheck=searchRange/2i 

for (int i^tlleLuminance-1:1)0;i--) 

[ 

leftToCheck-MatchSliceLiat[ 

Bllcelndex[i],tileToHatch.* bestSliceF, 
mlnDi stance JeftToCheck); 
if (lEftTDCheck<=0) break: 

] 

return minOistance; 


int MatchSllceList(Slice* slice.Imaged tileToMatch, 

SlicePtrfi! bestSlice* 

ulong& mlnDiatance.int leftToCheck) 

// Function MaKdiSUccList matehes slk^ b a list ^tgainst a tile. 

// Returns wljcn the list exliaustcd, or earikt if the Rsi is longer than 
// the pmametef leflToaieek. 

// Returns the reduced value of leftTbCheck. 

I 

while (slice] 

I 

ulong colorDiEtance= 

elementIma ges[slic e * > elementId], 

RawDlatance(slice.tileToHatch ^mlnDistance): 
if {colorDlstance < minDistance) 

[ 

inlnDl 31 an c e=c o 1 o rDi stanc e; 
bestSllce^slice: 

I 

if (--leftToCbeck <= 0) break: 
slice-sKce - >ne3tt: 

I 

return leftToCheck: 
f 


f: 

I //namespace 
#endif 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 

She’s Gotta Have It 


Using Media Sample References and 
Data References 


Introduction 

Iimgine that we’ve got a couple of dozen pictures from a 
digital camera and tliat we'd like to create a slide show movie 
from those pictures — that is, a QuickTime movie that displays 
each picture, in a predelerniined sequence, for a predetermined 
amount of time. The first thing we’d need to do, of course, is 
create a new movie file, track, and media (by calling 
CreateMovieFile, NewMovieTrack, and NewTrackMadia). Tlien we 
might proceed like this: open each piaure file, draw the picture 
data into an offscreen graphics world, compress the data, and 
add the compressed data as a new media s^imple by calling 
AddMediaSample. Then we would finish up by calling 
InsertMedialntoTrack and AddMovieResource. Voila, we've got our 
slide show movie. 

This strategy involves copying tlie picture data from the 
individual picture files into die slide show’ movie file, and lor 
some purposes that might he exactly what we want to do. But 
if we’re going to keep the picture files around anyway or if 
we re not sure we want to keep the resulting movie, it might 
he better to have our QuickTime movie file just point to the 
data in the picture files instead of having it contain a copy of 
that data. We can do this i>y inserting into the movie a media 
sample reference (or, more briefly, a sample reference) to tlte 
picture tile data. 

In this article, weTe going to work with media sample 
references. We ll begin by taking a look at how to create 
media sample reference.s, by developing a simple droplet 
application that creates a slide show movie from a number of 
picture files, as described above. As we'll .see, .sample 
references go hand in hand with data references, which we 
discussed at some length in an earlier QuickTime Toolkit 
article (‘'Soniew'here HI Find You" in MacTeeb, October, 2(K10). 


So we’il take this opportunity to investigate a couple of 
somewhat more advanced techniques for using data 
references. In particular, well see how to “flatten** a movie that 
contains a movie track, so that the child movie data is 
contained within the parent movie file; we’ll also see how to 
create a movie whose media data is contained entirely in 
memory and then save it into a file. 

Media Sample References 

In a nutshell, a media sample reference is a reference to 
some existing media data. Tlie idea is diat once we’ve got some 
media data stored in some location (a file, an object addressed 
by a URL, a block of memory, and so forth), we can reuse that 
media data by simply referring to it. That is, we don*t need to 
cojiy ihe data in order to get access to it. 

It's worth noting that we’ve bumped into sample 
references several times previously in this series of articles. 
Early on, when we di.scussed movie importers and exporters 
(in *‘ln and Out” in MacTech, May, 2000), we learned that 
QuickTime can import some types of files without having to 
make a copy of the file data. We say that these kinds of files 
are imported in place — meaning that the as.sociated movie 
importer constructs a movie that directly references the data in 
the file being imported. Now we can .see that a movie 
importer does thi.s by inserting media sample references into 
the new movie. T'hose references point to the data in the 
imported file. Importing in place, by using media sample 
references, allows the new movie to be created more quickly 
and uses less storage space (since the media data does not 
need to be copied). 

We also mn into sample references while we were working 
with the QuickT'ime video effects architecture, when we wanted 
to add a video effect to part of a video track, (See “F/X 2” in 
MacTeeb, October 2001.) The standard way to do this is to create 
a video new track iliat is a copy of tlie appropriate segment of 
the original video track; then we create an effects track that uses 
the copied track segment as its input, as showm in Figure 1. 


Tim Monroe in a mem her of the QuickTime engineering learn. You can contact him at monroe@apple.com. The views expressed here are not 
necessarily shared by his employer 
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figure 1: A filter applied to part of a video track 


The new video Crack can contain a copy of the media data in the 
original video track (^r it c'an contain only references to that 
media data. 


Creating Sample References Indirectly 

Let’s begin by reviewing the code we used to create the 
new track that we used as the input to our effects track. Listing 
1 shows the relevant section of code. 


Listing 1: Creating a copy of a video track segment 

QTEfft^:ts_Addr:fli\nToM(ivjt*Segmt^ 

mySrcTrackl = NewHovieTrackttheMovie. niyWidth, rayHeight* 
kNoVdlmne): 

If (mySrcTrackl = NULL} 
returnCpararaErr): 

mySrcMedial ^ NewTrackMedlatinySrcTrackl, VideoMediaType. 

myTimeScale, NULL, 0); 

If (mySrcMedial — NULL) 
returti (patrittiKtr) ■ 

#if C0PY_M0VTE_HEDTA 
myErr = BeginMediaEdits(mySrcHedial): 
if (myEri: !== noErr) 
return (ntyErr); 

#endif 

inyErr = CopyTrackSettings{myVidTrackl. mySrcTrarklJ: 
rayErr = InsertTrackSegnient (niyVidTrackl, mySrcTrackl. 

theStartTiine. theDuration. theStartTime) : 
if fmyErr != noErr) 
r eturn(myErr} \ 

#if COPY_HOVIE^MEniA 
EndHediQEdits(TnySrcMedial); 

//end if 

We call InsertTrackSegment to copy part of the original video 
track (myVidTrackI) into the track that will l>e used as the source 
tor the effect (mySrcTrackI). If the compiler flag 
COPY_MOVIE_MEDJA is set to 0, tfien we don't call 
BeginMediaEdits and EndMediaEdits to begin and end a media- 
editing session; in tills ease, the new track contains references to 
the media data in tlie original track, thereby minimizing the 
resulting tile size. 


Creating Sample References Directly 

So* one way to create sample references is to call 
InsertTrackSegment without having opened a media-editing 
session (that is, without having called BeginMediaEdits). A more 
direct way to create sample references is to use the functions 
AddMediaSampieReference or AddMediaSampleReferences. Both 
of these functions allow us to add to a media one or more 
sample references to some existing data (and hence the names 


are slightly misleading). The main difference between these two 
funaions is that when are adding a large number of samples to 
a movie at one time, AddMediaSampleReferences is significantly 
more efficient than AddMediaSampieReference, In this article, we 
will be adding only one sample reference at a time, so we’ll 
restrict our attention to AddMediaSampieReference, which is 
declared essentially like this: 

QSErr AddMediaSampieReference { 

Media theHedla, 
long dataOffset, 

Liuaigned long size, 

Time Value durationPerSaiuple, 

SampleDescript!onHandle samp1eDescrip11onE. 
long niJjnberOfSamples, 
short sampleFlags. 

TimeValue ^sampleTime}: 

'llie parameters here are identical to those for AddMediaSample, 
witli one exception: AddMediaSample also takes a handle to the 
data that is to be added to tlie media. With 
AddMediaSampieReference, weTe not adding any data, so we 
don’t need that parameter. 

Here’s how we might call AddMediaSampieReference to add 
a single media sample reference to a media: 

myErr = AddHedlaSampleReferGncetmyMedia, myDataOffset. 
mySize. myOuration. myDesc, 1. 0. NULL}; 

As you on see, the numberOfSamples parameter Is set to 1, the 
sampleRags parameter is set to 0, and the sampleTIme parameter 
is set to NULL (since we don't care to have the new sample time 
reairned to u.s). The other parameters are set to specific values 
determined by the application. For example, myDataOffset 
should specify the offset into the referenced media file (or other 
storage device) of the desired media data. In our sample slide 
show making application, myDuration will always be set to 600, 
so that eacli slide is displayed for one secontl. 

Now, how' does AddMediaSampieReference know where the 
original media data resides? As you knt>w, QuickTime uses cLtta 
references as its principal means of identifying the location of 
some data. So we might have expected that 
AddMediaSampieReference would take a data reference as a 
parameter But, alas, you can see abt)ve tliat tliere is no such 
parameter Instead, we need to attach the data reference to tlie 
media before we call AddMediaSampieReference; we do this by 
calling the AddMediaDataRef Function, like this: 

myErr “ AddMediaDataRef EmyMedia. ^leyDataReflndex, 

(Handle)rayAllas, tAllasType); 

AddMediaDataRef adds the specified data reference to the 
specified media and returns the index of that data reference in 
the media’s fist of data references, 'llien we assign that index to 
tlie data Ref Index field of the sample description that we pass to 
Add Medf aS am pie R ef e re n ee : 

(* *myDesc) ,dataReflndex = loyDataRef Index; 
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In tliis way, weVe i^iven AddMediaSampleReference a complete 
.specification of the location of the data for which it will create a 
sample reference. 

Getting Sample References 

QuickTime also provides the functions 
GetMediaSampleReference and GetMediaSampleReferences, 
which we can to get information about one or more samples 
that are stored in a media data file {or otlier media storage 
container). Unlike GetMadiaSample, GetMediaSampleRefarence 
does not return the actual media data to us; rather, it gives us a 
handful of pieces of information about the media sample(s), 
such as the offset within the media container of the sample data, 
the size of the sample data, and a sample description that 
specifies the format of that sample data. We saw [ust above that 
well need that offset and size when we call 
AddMediaSampleReference; well also need a sample description 
when weTe building our slide show movie. So w'e1l call 
GetMediaSampleReference like this: 

royE r r = Get Med i a S a ni p 1 eRe f e r en c e (my RefMe d i a ♦ 

&myDataOf fsEt. tiny Size. D» NULL. MULL. myDesc. 

NULL. 1. HULL. 0): 

Here, myRefMedia is the media to which we have a reference. In 
our slide show example, it1l be the data in the individual picture 
files. 

Slide Show Movies 

Let's illustrate how to work witli media sample references 
by tbuilding a slide show movie from a collection (if picture files. 
Wc want the user to be able to drop any number of picture files 
onto our application; when this happens, the application will ask 
the user to .specify a file name and location for the slide show 
movie; then it will create the movie and exit. Let’s call this 
droplet DropPix. 


Handling Dropped Files 

The first thing that DropPix needs to do is assemble a list of 
the files that the user has dropped onto its icon. In our 
Macintosh application, we can do tliis inside of our AppleEvent 
handler for file Open I3ocument event, as shown in listing 2. 


Listing 2: Keeping track of dropped files (Macintosh) 

QTApp_Haii(IleOpenDocumt:n(AppleEvejit 

// open each specified fUe 

for (mylndex = 1: mylndex <= atylteTDElnList : inylndex-H-) 
if (myErr = noErr) I 

myErr = AEGetNthPtrt&myDocList, mylndex, typeFSS, 
&ciyKeyWd. StnyTypeCode, (Ptr) ^nyESSpec, 
slzeof (myESSpeo) . SifflyActualSlze) : 
if (myErr = noErr) j 

gSpecs[rayIndex - 1] = myFESpec: 

I 

1 

if {myDocLlst.dataHendle) 

mylgnoreErr = AEDisposeUesc (&;iEyDocList J : 

gNumSpecs “ myIndex - 1; 

DropPix_HakeSlideSho’if() ; 

QTErame_QuitFrameworkO ; // act like a droplet and dose auioniaticaLly 


You’Q notice that we're using mo global variables, gSpecs 
and gNumSpecs, to keep track the file system specification records 
for the dropped files. We declare those variables like this: 

FSSpec gSpecs [kMaxNumPictureFiles] : 

short gNujp Specs; 

(ril leave it as an exercise for the enterprising reader to get rid 
of the Imd-coded array size.) 

On Windows, we can get a list of the dropped fiJes by 
reworking some of the code in the 

QTFrame_OpenCommandLineMovies function (defined in die 
file WinFramework.c). First we need to remove the existing call 
to SHGetFilelnfo that restricts our application to opening only 
QuickTime movie files. Then, once we've finished creating a 
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lile system specification record for a dropped file, we can add 
it to our array and increment our count of dropped files, as 

shown m Listing 3- 

Listing 3: Keeping track of dropped files (Windows) 

QTFrame_OpenCx}mmandLme Movies 

// ituike :m FSSpec record 

HativePathNameToFSEpec (rnyFileName. &:njyFSSpec . 

kFullHativePath]: 
gSpecs[rnyFilelndex] = myFSSpec: 
myFilelndex-H-; 

When we are done collecting the files, we finish up like this: 

gNuinSpacs “ niyFilElndex: 

DropPix_MakeSlideShow(): 


Creating the Slide Show Movie 

The DropPix_MakeSlicleShow function first elicits a movie file 
name and location from the user, so that DropPix knows where 
to put the output slide show mt)vie. Then it creates the new 
movie file: 

inyErr “ CreateMovieFile(fiiniyFlle, aigMoviePlayer. 

smCurrentScript. iiyFlags, i&myResRefHutit, EimyHovle): 

And, as usual, well create a new track and media: 
myTrack = f^EwMoviETrack(inyMoviet niyWldthp tuyHeigkt, 0); 
myMedta “ MewTrackMedia(!nyTj:ac.k. VldeoMediaType, 600, NULL,, 

0 ): 

Tlie hulk of DropPix_MakeSlideShow is a for loop that acids 
to this new media a sample reference to the data in each of the 
picture tiles in gSpecs, 

Retrieving the Picture Information 

Before wc can call AddMediaSampleReference, we need to 
get the offset (}f the picture data in its file, and we need lu add 
a data reference for that llle to the new media. Adding a data 
reference is easy; llrst we create a file data reference: 

myFrr ” QTNgwAIIes(( const FSSpec OigSpecsImyindex]. 

6inyAlias, true): 

Then we add it to the media: 

uiyRrc “ AddHediaDataRef (myMedia. 6inyDataRefIndex, 

(Handle)myAllas. rAliasType): 

How do we get the cjffset of the data in the picture file? 
Earlier, we saw that we eould use GetMediaSampfeReference to 
get information al^)ut samples that are stmed in li media data 
file, So all we need to do is call NewMovleFromDataRef to open 
the picture file as a movie and then call 
GetMedlaSampleReference on diat movie's media. Listing 4 
shows die sequence of calls here. 

Listing 4: Getting information about a picture file 

l>ropPix_MakcSlideSht>w 

// nttocuie a sample dtseripiion 

myDesc ^ (SampleDescriptionHandlelNewHandleiO): 
myErr = MemErtorO: 
if (oiyErr noErr) 
goto bailLoop; 

myErr = NewMovieFromEataRef (liniyReftlovie. 

newMovieDontRaaolveDataRefs. NULL. (Handle)rayAlias, 


rAliasType): 
if [myErr !== noErr) 
goto bailLoop: 

// get the first miok's media 

myRefTrack = GetMovleIndTrack(myRefMovie. 1); 

TnyRefMedia = GetTrackMedia(myRetTrack); 
if ((myRefTrack = NULL) || (myRefMedia = NULL)) 
goto bailLoop: 

myErr = GetUediaSampleReference{myRefMedia, ^myDataOffset, 
imySize, 0, NULL, NULL, myDesc. NULL, 1, NULL, 0) ; 


This gives us the data offset and die media sample size. It 
also gives us a sample description of the image, which we can 
use (for instance) to determine the size of the video track in the 
slide show movie. Our call to NewMovieTrack really Icxiks like 
this: 

myTrack = NewMovieTrack(myNovie, 

Long2Flx( {** (IinageDescriptionHandle)myDesc).width), 
Long2Fix[*(ImageDescriptionHandle)myDesc).height), 
kNoVoluTEo) : 


Adding a Sample Reference 

Now wc'r* iilinosr finislied. Wc add a sample reference to 
tlie data in the picture file like iliis; 

'myDesc) .dataRef Index “ tnyDataRefIndex: 
myErr = AddHediaSampleReferance(myNedia. myUataOffset, 
mySiae. myDnration, myDasc, 1, 0, NULL): 

Once we\e done this for each picture file dropped onto 
our application, we need to call insert Medial ntoTrack and 
AddMovieResource in the usual way. Listing 5 sho%vs 
DmpPix^MakeSlideShow in its full glory. 

Listing 5: Creating a slide show movie 

DropPix^ M:ikcSlideShow 

OSEtr DropPix_NakeSlidaShow (void) 

[ 

Movie myMovie “ NULL: 

Track myTrack = NULL: 

Media myMedia = NUTX: 

FSSpec myFile: 

Boolean mylsSelected = false: 

Boolean mylsRaplacing = false; 

StringPtr myPrompt “ 

QTQtils_ConvertCToPasc3lString(’'Save movie as:"): 
Strin^Ptr myFileName = 

QTUtils_Conve rtCToPascalString("Untitled.mov"): 
long myFlags = createMbvieFi1eDeleteCurFile | 

crGateMovieFileDontCreateResFile: 
short myResRefNuni “ kInvalidFlleRefNum: 

short myResTD “ movlelnLlataForkResID: 

short ruylndex: 

OSErr myErr - noErr: 

If (gNumSpecs 0) 
return iparamErr]: 

// prompt the user f«r lik nmiie 

QTFrame_PutFile (myProinpt. myFileNajiie. fiftnyFile, 
fiiinylsSelec led , imylsRepIaclng) r 
myErr = mylsSelected ? noErr : userCanceledErt; 
if (myErr != noErr) 

goto bail: 

// ddetc any exij^ting flit of that name 
if (mylsReplacing) I 

myErr = DeleteMovieFile(^niyFile) : 
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if (myErr != noErr) 

^otQ bail: 

) 

// trrtMte a movie fik for the destination movk 

tnyErr ^ GreateiiovieFile (fiitoyFile < sigMoviePlayer , 

stnCurrentScript, myFlags > &myRe:sRefNum, fitrayMovie}: 
if (myErr noErr) 
goto bail: 

// add a sarapJe reference for each image to the new movie 
for (myindex ~ 0; cuylndex < gNuniSpeas: mylndex-H-) \ 
short tayDataRef Index = 0; 

long myDataOffset, mySize; 

SaatpleDascriptionRandle 

myDesc = NULL: 

TlmeValue myDuration = 600; 

AllasHandlemyAlias = NULL: 

Movie myRefMovie = NULL: 

Track myRefTrack = NULL: 

Media myRefMedia = NUI^L; 

myErr = QTNewAlias((const FSSpec *J&g£pecs[myindex], 
StinyAlias, true) : 
if (myErr noErr) 

goto bailLoop: 

// allocate sample doiieriptlon 

inyDesc = (SampleDescriptionHandlelNewHandleCO); 
myErr “ HeiixError f}: 
if {myErr ]- noErrJ 
goto bailLoop: 

myErr = NewMovieFroiiiDataRef(&iny Ref Movie. 

newMovieDorvtReaolveDataRefs , NULL. (Ilandle}iiiyAllas. 
rAliasType): 
if (myErr noErr) 

goto bailLoop; 

// get the first track’s media 

myRefTrack GetMovielndTracklmyRefMoviG, 1); 


myRefMedia - GetTrackHedia(inyRefTrack): 
if {(myRefTrack = NULL) |[ [myRefMedia ^ NULL)) 
goto bailLoop: 

myErr = GetMGdiaSampleReference(myRGfMEdla. 

&myDataOffset. ^mySixe* 0. NULL, NULL, myDesc. 
NULL. 1. NULL. 0): 
if (myErr != noErr) 
goto bailLoop: 

if (myTrack ^ NULL) ( 

// create the movie track and media 
myTrack = NewMovieTrack(myMoviG. 

Long2Fix((* *(ImageDescriptionHandlejinyDesc).width)* 
Long2Fix((* *(ImageDescriptionHandle)myDeac).height). 
kNoVolume): 

myErr = GetMoviesError(}: 
if (myErr noErr) 
goto bail; 

myMedia ^ NewTrackHedia[myTrack, VideoMediaType. 600. 
NULL. 0): 

myErr = GetMoviesError[): 
if (myErr 1= noErr) 
goto bail; 


// add a data reference to the media 

myErr ^ AddHediaUataRef(myMedia, 6iinyDataRefIndex, 
(Handle)tnyAllas. rAliasType); 
if (myErr != noErr) 
goto bailLoop; 

(**TnyDesc) .dataRefIndex = itiyDataRefIndex: 

// add a media sample reference to the media 

myErr “ AddMediaSampleReferenca(myMedia, imyDataOffset. 
mySize, myDuration. myDesc. 1. 0, NULL); 

bailLoop: 

if (myDesc) 
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DLEpo3eHandle{ (Handle) JnyDesc) : 

] 

// add tlic media to the track 

layErr = InsertMedialotoTrack(myTrack* 0, 0, 
GetMedlaDuration(niyMedia). flxedl) ; 
if (rayErr 1“ noErr) 
goto ball: 

// add the movie atom to the movie file 

myErr = AddMovieResource (myMovie» rDyResRefNumi, iStiayResID, 
NULL): 

bail; 

if (myReisRefNuiii 1 = klnvalidFilaRefNum) 
CloseHovieFileCmyReaRefNiim): 

if (tuyMovie != NULL) 

DiBposeHovie(myHovie); 

free (ayPrompt ) : 
f rest toy FileNanie) ; 

return (tnyErr): 


As you can see, die size of the slide show video inick is 
determined by the size of the first picture file in gSpecs. Each 
remaining image is scaled to fit into that track rectangle, which 
may result in some disttirtion of the image, fll leave it as an 
exercise for the reader to figure out a way to avoid that distonion. 

Movie Tracks 

A movie track is a track of type MovieMediaType that 
effectively emlieds one movie inside of another, as illustrated in 
Figure 2. I'he key feature of using movie tracks — instead of 
just layering one track on top of another track — i.s that the 
parent and child movies can have different time bases, so they 
can (for instance) have different playback rates and different 
kx ip ing cha ra cl e ri s ties. 



Figure 2: A child movie imide of a parent moine 

You may recall from our earlier discussion of movie tracks 
(in “Atomic Cafe’' in McicTech, Septemlier 2(X)0) tliat a media 
sample in a movie track consists of an atom container whose 


atoms specify the movie that Is to be embedded in the main 
movie, as well as some of the playback characteristics of the 
embedded movie. The media sample does not typically contain 
the data for the child movie itself; rather, it points to that data 
using an atom of type kMovieMediaDataReference; this atom 
contains a data reference to the child movie data, which is most 
often a file data reference or a URL data reference. 

It would be nice if there w^ere a way to save a movie that 
contains a movie track, so that all the media data — for the 
parent and the child movies — is contained within a single file. 
This is actually quite straightforward, using a data reference 
extension. The essential idea is to simply append all of tlie 
child movie data to the data reference atom in the appropriate 
media sample. By suitably reconfiguring the data reference 
atom, we can force QuickTime to look in the data reference 
extension for the child movie data instead of resolving the data 
reference in that atom. 

In the process of rectinfiguring the data reference atom, 
well need to use a few techniques that are interesting in their 
own right. We ll need to learn how to get the data for a media 
sample at a specific movie time, and well need to learn how 
to replace an entire media sample in an existing movie* So 
let’s get started. 

Getting the Current Media Sample 

A movie track (that is, a irack of type MovieMediaType) can 
have one or more media samples, each of which is an atom 
container whose atoms pick out a child movie and specify its 
spatial layout and playback characteristics. We can get the media 
sample for a given movie time by calling GetMediaSample. The 
only “gotcha" is that GetMediaSample requires that this time lie 
expressed in tlie media’s time scale. To convert a movie time to 
the corresponding media time, we can call 
TrackTimeToMediaTime, as illustrated in Listing 6. 

Listing 6: Getting the current media sample data 

QTMIM J'LiltenCMdlnioPiircnt 
Handle mySainple “ NULL; 

SampleDesCriptiaiiHandle oiyUesc == NULL: 

TimeValuE utyMovleTlraeNow = 0; 

TimeValue ntyHediaTiineNow “ O j 

TimeValue myDuratlon = 0: 

mySample = NawHandleClear(O): 
if (mySaraple — NULL) 
return(MemError()); 

iiiyDesc = (Saniplel}escriptionIl3ndle)NewHandleClear(0) ; 
if (inyDesc = NUia.) f 
myErr “ MemErrorO: 
gato ball: 

myMovieTliiiGNov ^ GEtMovieTini 0 (inyHovie ♦ NULL) : 
if (myHovieTinifiNow ^ GetMovieDuratlon (rnyMovie)) 
inyHovieTimeNow- : 

myMediaTlmeNow = TrackTimeToMediaTiine [oiyMovleTlmeNow, 
myTrack): 

If CrayMediaTinieNow “1) [ 
myErr = invalldTlme: 
goto bail: 
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rayErr = GetMediaSarapletmyHedia. nySample, 0. NULL, 

inyHediaTlmeNow, MULL, ficmyDuratlon, myOeBc. NULL, 1, 
NULL, NULL): 

TrackTimeToMediaTime returns -1 if tliere is no medm 
sample in die track at the specified movie time or if die specified 
movie time is outside the movie’s active segment. Since we call 
GetMovieTime to get die current movie time, we’re guaranteed 
that myMovieTimeNow will be within die active movie segment. 
(Notice that we decrement the movie time if we happen to he at 
the end of the movie.) 

The time passed to GetMedtaSample can be any time within 
the extent of the media sample, GetMediaSample retrieves tlie 
data for that sample and returns it in the handle we pass it Chere^ 
mySample), GetMediaSample also retum.s the duration of the 
media sample. 

Loading the Child Movie Data into Memory 

The media data, to repeat, is an atom container that holds 
at least a data reference atom that picks out the child movie. We 
can get that atom like this; 

tnyAtom = QTFindChildByrTidextmySantple, 

kFarentAtanlsCaiitalner. kHovieMedlaDataReference, 

1. NULL); 

[f myAtom is non-zero, then we want to fetch the ckita in that 
atom. Tile data Is a data reference prefixed by the data relerence 
type. We can get the daui reference and its type like this: 

QTGetAtoMDataPtr(mySample, rayAtoiti, SitnyDataSlze, 

&jjiyDataPtr) r 

myDataRefType = EndianU32_BtciN (* (USType * )myUa.taPtr): 
myErr ^ PtrToHand [inyDataPtr + slzeof (OSType), 

EimyDataRef, myDataSlze - slzeof COSType)): 

If tills is all siiccessfuh then myDataRefTypG is the data 
reference type and myDataRef is the dala reference itself Right 
nowL we want to open the child movie specified by ihai data 
reference and load it completely into memoiyv To open the child 
movie, w'e can use NewMovieFromDataRef: 

NewMovieFroniDataReft&riBYChlldMovie, 0, NULL, tnyDataRef, 
snyDataRefTypeJ ; 

To load the movie's media data completely into memory, 
we can use Flatten Movie Data, passing it a handle data reference, 
(WeVe used this trick previously, in "Somewliere I'll Find You", 
cited earlier.) Listing 7 shows the essential steps. 

Listing 7: Loading a child movie into memory 

QTMIM ^FlattenChi IdlnttJpanrnt 

UataReferenceRecord myDataRefRecord: 

Handle myDataRefHandle = NULL: 

Handle myHandleDataRef = NULL: 

inyDataRefHatidla = NswHandleClear (0) : 
if (myDataRefHandle = NULL) 
goto bail: 

oiyHandleDataRef = QTDR_MakeHandleDataRef(myDataRefHandle) : 
if (myHaTidleHataRef = NULL) 
goto bail: 


myEataRefRecord,dataRefTypB = HandleDataHatidlerSubType; 
myDataRefRecord.dataRef = myHand1eDataRef; 

EiiyHenioryMovle “ FlattenMoviGData{myChildMovie, 

flattenFSSpecPtrlsDataRefRecordPtc | 
fla 11 enAd dHoVieToBs t aFo rk, 
(FSSpecFtr) Sciny DataRef Record. 
sigMoviePlayer* 
smSystemScript, 

OL) : 

myErr = GetMoviesError {) * 
if [myErr != noErr) 

goto bail; 

DieposeMtivie(myCblldMovle): 

Notice tixit tile second parameter passed to FlattenMovieData 
contaias the flattenFSSpecRrisDataRefRecordPtr Oag, which indicates 
iliat the ihiicl parameter is a pointer to a dita reference record, not 
a pointer to a file system specifiaition record; it also contains the 
flatlenAddMovieToDataFork Hag, which tells FlattenMovieData to write 
the movie atom as well as tlie media data into the specified loc^ation. 
If we didni specify flatlenAddMovieToDataFork, we'd get only tlie 
media data in die child movie, 

Crcfating a ‘"Flattened" Child Movie Media Sample 

Recall that w^e w^ant to replace the original data reference in 
the data reference atom in the child movie media sample by a 
new data reference that has the child movie data appended to 
it, 'lliat is to say, we w^ant to attach a data reference extension 
to that original data reference. In this case, the extension is of 
type kDataRefExtensionlnitializationData. Let’s call tliis kind of 
extension an initializalkni ckita data refereuev CKxtemion — or, 
more briefly, an mitialization externkm. 

QuickTime uses an initialization extension in one ca,se only: 
when tlie data reference is a handle data reference and the 
specified handle is NULL. When tliis happens, QuickTime takes 
the data directly from tlie initialization extension. In effect, we 
c'lm use this type of data reference extension to shoft-circuit the 
normal data reference resolution fliat QuickTime would 

otherw ise perfonn; we re saying; here is the data youTe looking 
foL in this data reference extension. 

So tjur task boils down to this: replace the existing data 
reference in ilie atom of type kMovieMediaDataReference by a 
handle daia reference whose associated data is NULL; then 

append a data reference extension of type 

kDataRefExtensionInitializationData to that data reference. For 
this latter task, we’ll use the utility function 

QTDR_Add!nitDataDataRefExtension, defined in Listing 8. 

Listing 8: Adding an initialization da^ data reference 
extension 

QTDR_ALkl I n it DataOataRefExtt nsiion 
OS E r r QTDR_Ad dInit Da t a Da t aRe f Ex t e nsion 

(Handle theDataRef, Ftr thelnitDataPtr) 

[ 

tin signed long myAtomHeadet [2] : 

GSErr myErr = noErr; 

if (thelnitDataPtr ^ NULL) 

return(paramErr): 

myAtomHeader [0] “ EndianU32_NtoB(sizeof(myAtomHeader) + 
GetPtrSlze(thelnitDataPtr)); 
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myAtoraHeadertl] = EndiaiiU32_NtoB ( 

kData^efExteiLslonlnitial lKationData) i 

myErr “ FttAndliaTicKiiiyAtaiiiHeader, theBataRef, 
sizeaf (myAtcFtEiHeadei:)) i 

if {myErr = noErr) 

myErr = FtrAr>c!Kand(theIidtDataPtr, theDataRef* 
GetPtrSize {theInltD.ataPtr)) i 

retyrn (myErr); 

I 


Listing 9 shows the code we use to replace the original 
data reference atom by a new^ data reference atom that contains 
tl^e data of the child movie. 


Listing 9: Replacing a data reference atom by a “flattenffd" 

atom __ 

QTMlM_FLittcnChUdlni(>Paa'ni 

// out wUh the old,-. 

QTRe Kio V eAt cf m f my S amp 1 e . my At om) : 

// ...ajid in wUh the new 

myChildDataHandie “ NewHandlEClear(sizeof(OSType) + 
sizeof[Handle)) r 

if (myChildOataHsndle 1“ NULL) I 
OSType myType; 

// set the data reference t> pe 

tnyType = EndianU32_NtDB(RandlEBataHatidlerStibType): 
BlockMovet^itnyType, ‘ myChi Id Data Hand le, Eizeof (OSType)) t 

// leave the next four bytes set tu tIxtHKHKKKK); 

// add a filenaming extension and an initiali/.atit>n extension 
myErr ^ QTDR^AddFilenamingExterteionftnyChildDataHandle* 
mJLL): 

if (myErr 1“ naEtr) 
goto ballr 

HLock(myDataRefllaTidle): 

myErr QTDR^AddlnitDataDatsRef Extension 

(myChlldDataRandle* •myDataRefHandle); 
Hllnlock(myDataRefRandie): 
if (myErr [“ noErr) 
goto bail; 

HLockCmyCbildDateHandle): 

myErr = QTInsertChild[mySample. kParentAtoraTsContainGr, 
kMovleWediaDataReference» 1, 


GetHand1eS1ze(myChi1dD at aH and1e)* 

•myCbildDataHandle. NULL); 

HUnlock(myChxldDataHandla); 
if (myErr != noErr) 
goto ball; 

Notice that we need to add an empty filenaming extension 
before we add the initialization extension. 

Replacing a Media Sample 

One final step remains, namely to replace the original 
media sample by the revised media sample. To do this, we first 
need to delete die track segment conesponding to the original 
media .sample. Then we'll add the new media sample into die 
media and insert it into die track at that time. 

It’s easy enoiigli to figure out the start time and duration of 
a particular media sample. Recall that we already have the 
airrenl movie time stored in the variable myMovieTimeNow, We 
can then call GetTrackNextlnteresting!ime twice, asking it to 
search backward and forward fur the liuundaries of the currenl 
media sample: 

CotTruckNextlaterestiugTitie (iiiyTrack, 

oextTiraGHediaSsraple 1 irextliroeEdgeOK, 
rayMovieTimeNow, OxOiDOO, tnryNovioStartTiffieH NULL): 
GetTrackNextIntGrGstingTiitie(iiiyTrack* 

UGxtTlraeModiaSample 1 nextTlTneEdgeOK.. 

myHovlcStartTiEije. 0x01000. NULL. fcniyMovieOurationJ: 

'llien we can call DeleteTrackSegment to delete the track segment 
occupied by tlie media sample: 

Del et eTrsekSegEnent (myTtaek, myNovl^StartTiine . 
myNovleDuratloti); 

Then we proceed as usual, opening a media-editing session 
and adding the new media sample to the media. The key step 
here Ls a call to AddMediaSample: 
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my Err = AddHediaSampleCinyMedla. 
mySample^ 

0 * // m tiffsci in ihvi 

GetSaudieSizefmySample). 
my Du r at 1 0 n * // fhme duration 

(SampleDeaeriptionHandlelmyDesc. 

1, // one sample 

0. // selfcontaiDcd samples 

&iiiyNe\tfTlme) ; 

Fimilly, we insert the media inla the track at the desired 
time and for the desired duration: 

myErr ^ InsettMadialntoTracktayTrack* myMovieStartTime, 
inyNewTime, myDuratlon, (FixedJOxOOOlOOQOL)■ 

And we are done! Lkting 10 shows the complete process in one 
handy routine. 

Listing 10: Flattening a child movie into the parent movie 

me _ __ 

QTMIM^FIattenChiJdlntciParmt 

OSErr QTHIMJlattenChildlntoPareTTt 

(WindowObject theWindowObject) 


Movie 

ayMovle “ NULL: 

Track 

ayTrack = MULL: 

Media 

myMedia = NULL: 

Handle 

mySample = NULL: 

Samp1&Deecr1ptionHandle 

myDesc “ NULL: 

TimeValue 

myMovleTimeNov = Q: 

TimeValue 

myMediaTimsNow = 0: 

TimEValue 

myDuration “ 0: 

QTAtoa 

myAtom = 0: 

Pti 

myDataPtr NULL: 

Handle 

myDataRef = NULL: 

long 

myDataSize “ 0: 

OSType 

myDataRefTypG: 

Movie 

myChlldHovie = NULL: 

Movie 

myMemoryMovle = NULL: 

DataReferencoRecord 

myDataRefRecord: 

Handle 

rayDataRefHandle - NULL: 

Handle 

rayHandleDataRef ^ MULL: 

Handle 

isyCbildDataHandle = NULL 

Fixed 

myRate: 

TimeValue 

myHovleStartTime ^ 0; 

TimeValue 

myMovieDuration * 0: 

TimeValue 

myNewTlme = 0: 

OSEcr 

myErr ^ noErr: 

if (theWlndowObject 

NULL) 


return {parariErr}: 


// rtiuiitl up the usual suspects: the parent movie, movit track, and movie track 
media 

myMovie ” ('^tiheWindovObject)-fMovie: 
if (myMovie = NULL) 
return(invalidHovis) t 

myTrack GetMovielndTrackTypeCayMovie^ 

HovieMediaType, movieTrackMediaType); 
if (myTrack “= NULL] 
returndnvalldTrackJ: 

rayMedia ^ GetTrackMedia(myTrack)t 
if (njyNedia = NULL) 
return(invalidHedia3; 

// get the child movk sample data 

// if the pjirent movie ts playing, stop it 
rayKate = GetHDvieRate(myMovie): 

SetHovieRate(tnyMovie. 0); 

niySamplE ^ NewHandleClear(0]: 

If [mySample = NULL) 
return {MetnError ()): 


myDesc ^ (SarapleEescriptionllandle)HewHandleClear |D): 
if UyDesc = NULL) ! 
myErr = MetnErrorO ; 
goto bail: 


myMovieTimeNow ^ GetMovleTime(myMovle. NULL): 

If (inyMovieTiineNow “ GetMovieDurationtmyMovie)) 
myMovieTimeNow--: 

rnyMediaTimeNow “ TrackTlnieToMediaTiDte (rayMovieTitneNow, 
myTrack): 

if (uiyMedlaTlnieNow ^ - 1 ) 1 
myErr = invalidTime: 
goto bail: 


myErr = GetMedlaSample(myKedia. mySample, 0, NULL* 

myMediaTImeNow. NULL, fitmyDur a tion, ByD e ac, NULL * 1. 
NULL, NULL): 
if (myErr !- noErr) 
goto bail: 

// tlic media s;mipk is an atom etmtainer; 

// fmd the duLi reference atom inside tlic media sample 

myAtom = QTFindChildByIndeK(mySaniple, 

kPacentAt qbIsC ontainer * kHovieMediaDatsReference * 

1, NULL): 

if (myAtOB 0) 1 

// get tlie data itrfcience att}m data 

QTLockContainer (BySantple): 

myErr = QTGetAtoniDataFtr{iitySample* ntyAtotn* imyDataSize, 
fiiinyDataPtrJ: 
if {ayErr noErr) 
goto bail: 

ayDataRefType = EndlanU32_BtoN[V(OSType *)myDataPtr): 
myErr = PtrToHandCmyDataPtr + aizeof{OSType)* 

SimyDataRef* rayDataSlze - slzeof (OSType)) ; 
if (ayErr [" noErr) 
goto bail: 

QTUalockContainer(mySample3 ; 

// open the child mt^vk and flatten it entirely into memory 

myErr “ NewMovieFramDataRef(imyChildHovle. 0, NULL, 
ayDataSef. myDataRafType): 
if [ayErr 1= noErr) 
goto ball: 

myDataRsfEandle = NewHandleClear(O): 
if (ayDataReftlandle == NULL) 
goto bail: 

ayRandleDataKef " 

QTM_Makellandlei}ataKef (ayDataRefHandle) ; 
if (myHandleDataRef = NULL) 
goto bail: 

ayUataRefRacordtdataRefType * HandleDataHandlerSubType: 
myUataRefRecord,dataRef ^ myHandleDataRef: 

myHetflDryNovfle - FlaCtenMovieUata [ayChlldHovie * 

flattenFSSp&cPtrlsDataRefRecordFtt | 
flattenAddNoviaToDataFork, 

{FSSpeePtr) fitrayDataRefReco rd, 
sigNovlePlayet * 
emSystemScript* 

OL): 

ayErr GetMovieaError(): 
if (myErr 1= noErr) 
goto bail: 

MsposeHovle (myChildHovie); 

// repbee tile existing ihia reference atom by a “flattened" data reference atom 
// out with the old.., 

QTRemoveAt oa (my Samp 1 e * my A tom): 
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// .. ;ind in W[Ltt the new 

myChildDataHandle - NewHandleClear(slzeof(OSType) + 
sizeof(Handle )]; 

if (myChildDataHandle != ^^ILL) 1 
OSType myType; 

// set ihe dm reference tjpe 

jnyType = EEdianU3Z_HtoB(HandleDataHandlerSubTypeJ; 
B1 ockMove [ &myType , * myCMldDataHandle, 
sizeof(OSType)); 

// leave the next four bytes set to 0 k(1(M)(KMK)(}; 

// add a filenaming extension and an initialization extension 
jnyEri: = QTDR_AddFiXenaminaExtension 
(myChildDataHandle, NULL): 
if (myErr [= noErr) 
goto bail: 

HLock(myDataRefHandleJ : 
myErr = QTDR^AddlnitDataDataRefExtension 
(myChildDataHandle. *myDataRefHandle); 

HUnlock[myDataRefHandle): 
if [myErr 1" noErr) 
goto hail: 

HLock(myCbildDataHandle): 
myErr “ QTInsertChild(mySamplet 

kParentAtomlaCotitainer, kMovieMedlaDataReference♦ 
1. 1, GetHandleSlze(itiyGMldDataHandle). 
'myChildDataHandle. NULL); 

HLfnlock(myChildDataHandle) : 
if (myErr 1^ noErr] 
goto bail: 


// add the new sample to the media 

// determine the bounds of this sample in movie time 
GetTrackNextIntersStingTlmetmyTrack* 

nextTimeMediaSampla | nextTimeEdgeOK, 
myMovleTimeNow. -0x01000, &myMovieStartTime, NULL): 
GetTrackNextIntersstingTlme[myTrack, 

nextTimeMediaSample | nextTimeEdgeOK, 
myMovieStartTime. 0x01000, NULL, &myHovieDuratian); 

// splice this media over the old one 
DeleteTrackSegment (myTrack, myNovieStartTime t 
myMovieDuration): 

myErr “ leginMediaEdits[myHedia); 
if {myErr !- noErr) 
goto bail; 



THE BEST SELLING INTERNET COMPONENT 
SUITE FOR WINDOWS, JAVA, LINUX, 
SOLARIS, AND MORE... 







IP*Worl€Sl 

The Only Truly Comprehensive 
Internet Toolkit 

“ More Than 30 Components Cover 
All Major Internet Protocols 

“ Follows Exact RFC Spedftcatioris 

- Market-Tested For Oyer 7 year>^ ^ ' 

- In Use By Almost All Fortune SOOs 


- Royalty-Free Pricing 


• J 


IP* Works! far Mac OS X (10.0/10,1/10.2) gives you 
access to a host of new capabUhies that will connect 
your applications to the Internet with unprecendent- 
ed easy of use, power, and flexibility! Your will be 
able to easily and quickly: 


- program the web: HTTP, WebForm, WehUphad 

- cat! web services: SOAP, XMLp 

- transfer files: FTP, TFTP 

- send email: SMTP, FileMailer, HTMLMaiJer 

- receive email: POP, IMAP 

- read/post news: NNTP 

- encode/decode: MIME, NetCode 


fi write a new media sample into the track 
myErr = AddMediaSample[myMedia. 
mySample, 

0. // no offset in data 

CetHandleSlzn(mySampla), 
myD u r a t i 0 n ♦ // frame duration 

(SaropleDescriptlQnHandie)rayDesc. 

1, // one sample 

0 1 // seif-contained samples 

^imyNewTime): 
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myErr = EndM&diaEdits(myHedia}; 
if (myErr noErr) 
goto bail; 
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// add the metlia to the track 

myErr ■= InsertMediaIntoTrack(myTrack, myMovieStartTime, 
myNewTime, myDuration, (Fixed)0x000lOOOOL): 


j else I 

myErr ^ cannotFindAtomErr; 

) 

bail; 

if (mySample != NULL) 
DisposeHandle(mySample) : 

If (myDesc 1= NULL) 

DisposeHandle ((Handle)myDe!Sc); 
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if (rayDataRef !- NULL) 

DiepofieHandle (tnyDataRef) : 

if (tnyDataRefHandle NULL) 

DisppaeHandl^(myDataRefUandle )) 

if (rayHandleDataRef != NULL) 

DisposeHandle(inyHandleDataRef) ; 

if (inyChildDataHandle 1= NULL) 
OisposeHandle(myChildDataHandlE) ; 

// restore the original movie rate 
SetMovieRate(n]yMovie, my Rate); 

rEtiufn(iiLyErr): 

] 

As written, QTMIM^FIattenChildintoParent replaces the 
current movie media sample by a “flattened" sample. It 
would be easy to adapt this routine to iterate through all 
samples in the movie track and to Ratten each child movie 
into the parent movie. 111 leave this refinement as an exercise 
for the reader. 

Memory-Based Mo\ies 

Let’s finish up this article by taking a look at a few ways we 
can create movies or tracks whose media data is contained 
entirely in memoiyr Tins is a useful thing to do for a number of 
reasons. For example, we might generate all of a Jiiovie's media 
data dynamically and not want to have to create a disk file to 
hold that drita. Or we might want to add a track io an existing 
movie hut don’t want the track’s tnedia data to be added to the 
associated movie file unless the user explicitly recjuesls it. fn that 
case, we can tell the track to store its media data in memory’, not 
in the original movie file. 

The key element here is to create a handle data reference 
and to set it as the data reference for the movie iof track). Any 
media tlata written to the movie (or imck) will be written into 
memory, at tlie location specified by the data reference. 

Creating Movies in Memory 

In a previous article ("Somewhere I’lJ Find You", cited 
earlier), we saw flow to create a movie whose associated media 
data is contained entirely in ITAAl, There, we took advantage of 
the fact that FlattenMovieOata can flatten a movie into a location 
specified by a data reference instead of by ii file system 
specification record. Listing 11 shows the core of our code for 
doing this. (This should remind you of Listing 7 alx>ve.) 

Listing 11: Flattening a movie into memory 

QTApp^ilanJk'Mcnu 

Movie myNewMovie NULL: 

Uandle myDataRef * NULL: 

Handle itiyHandle = NULL; 

DataReferenceRecord myDataRefRecord: 

myHatidle = NewHandleClear(0) : 
if (itiyHandie = NULL) 
goto bail; 

myDataRef = QTDR^MakeHandleDataRef(myHandle): 
if (jnyDataRef = NULL) 
goto hail; 

myDataEef Record.dataRefType = HandleDataHandlerSubType: 


niyDataRef Record. dataRef = tnyDataRef; 

myNewMovie ^ PlattenMovieData(iByMovie, 

flatteaRSSpecFtrlsDataRefRecordPtr ^ 
(FSSpeePtr)^myDataRefRecord. 
sigHoviePlayer, 
smSystemScript. 

OL) : 


Using FlattenMovieData assumes that we already have a 
movie (mylVlovie) and want to copy it entirely into RAM, It’s 
sometimes also useful to create a new movie in RAM, using the 
NewMovIe function and our standard calls to MewMovieTrack, 
MewTrackMedia, and so forth. The easiest way to do this is to set 
tfie movie’s defauit data reference to a handle data reference, 
using the SetMovieDefaultDataRef function. We can call 
SetMovieDefaultDataRef like tliis: 

inyErr = SetMovleDefaultDataRef (loyHovie , inyDataRef, 
HandleDataHandlerSubTypa) : 

Listing 12 defines a function, QTDR^CreateMovielnRAM, 
that creates a new movie w^hose media data is stored in a block 
of memoiyi 


Listing 12: Creating a movie in memory __ 

ginR.CaatcMovidiiRAM 

Movie QTDR_CrEateMovieInRAM (void) 
t 

Movie inyNovie == NULL; 

Track inyTrack ” NULL: 

Media myriedla = NULL: 

short inyResRGfNum = 0; 

short myResID = 0; 

Handle myDataRef “ NULL: 

Handle tiiyHandle - NULL; 

FSSpec myFSSpec; 

OSErr myErr - noErr: 

// cresite ;i new handk to hoJd thf media data 
myHandle = NewHandleClear(0); 
if CiiiyHandle NULL) 
go-to bail: 

// creitto :l rrlhrenct to thiit Imdit 
myDataRef = QTDR_MakeHandleDataR 0 f(myHandle); 
if (myDataRef -- NULL) 
goto bail: 

myMovie = NewMovie(newMovisActive): 
if (myMovie ™ NULL) 
goto bail: 

myErr “ SetMovieDefaultDataRef(tnyMovie, myDataRef. 

HandleDataHandlerSubType); 

If [myErr != noErr) 
goto bail; 

// rresUf the movie tnsek and media 
myTrack = NewMovieTrack(myMovie. 

FixRatio[kVideoTrackWldth. 1). 
FlxRatio(kVldeoTrackHeight, 1). kNoVolume): 
myErr = GetMoviesError[): 
if (myErr J” noErr) 
goto hall; 

mvMedla = NewTrackMedia(myTrack. VideoMediaType, 
kVideoTimeSeale. NULL. 0); 
myErr = GetMoviesError{); 
if (myErr i= noErr) 
goto hail: 

// create the media hamplcs 

myErr = BeginMediaEdits(myMedia): 

If (myErr noErr) 
goto hail; 
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myErt = QTDR_AcidVideoSaiiiplesToHedia( my Media, 
kVldeoTi:ackWidth, kVideoTrackHelght] ; 

if (myErt 1= noErr) 
goto ball; 

inyErr = EndMecilaEdits (myMedla) : 

if (myErr E= noErr) 
goto bail; 

// add the media to the track 

myErr = InsertHedialntoTrackCmyTrack. 0, 0, 
GetMediaDiiratlon(iiiyHedia) , fixed 1) ; 

if (myErr 1= noErr} 
goto bail; 

// add the movie atom to the movie file 

Ad.dMovieR€soui:ee{myMovie, rayResRefNuin, SirayReslD, NULL): 
bail: 

If (layDataRef != MILL) 

DisposeHandle(myDataRef): 

return(myMovie): 

I 


Tliis function is virtually identical to other movie-creating 
functions weVe seen in previous articles, except tliat it CkiUs 
SetMovieDefaultDataRef to clause all media data to written to a 
hkxk of memory'. Previously, we relied on tlie tact that a new 
movie’s default data reference Ls the file Ofxmed by a c’till to 
CreateMovieRle or NewMovieFromRIe. Here we are calling NewMovie 
to create a new movie with no attachment to any existing tile, so 
w^e need to explicitly set the niovie^s default dalii reference. 


If we want just a panicular track to have its media data in 
memory, then we can pass a handle data reference when calling 
NewTfackMedia. like this; 

myMedia = NevTrackMedia(myTrack, VideoMedlaType, 

myTimeScale, myDataRef. HandleBataHandlerSuhType): 

The specified data reference overrides die default movie 
data reference. 

Saving Movies from Memory 

In all these cases, wx^Ve ended up with a movie that has 
some or all of its media dam stored direedy in memory, accessed 
using a handle data reference. We can, of course, play the 
movie, edit the movie, enable and di.sabie tracks (and so forth), 
exactly as if the media data were contained in a file accessed via 
a file data reference or stored remotely and accessed via a URL 
data reference. But wliat happens if we want lo save this movie 
tnio a fiJe on disk? Well, it depends. If we created the movie 
entirely in memory (as in Listings 11 and 12), then tmr 
undedying application framew^ork code will detea that no file is 
attached to the movie yet. In this aise, it will elicit a filename 
from tile user, create a new file (or delete and recreate an 
existing file), and then c'all FlattenMovieData to wmte the media 
data into the new file. FlattenMovieData strips out any unneeded 
media s;miples, resolves all remaining media sample references, 
and writes the media data into the movie file on disk. This movie 
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file a)ntaiiis only file data references, [t’s a self-contained movie 
file that liolds all of its media data. So far^ so good. 

Things start to get interesting, however, if we’ve already 
got a movie file attached to our movie. (Thi.s would happen, 
for instance, if w^e open an existing movie file and then add 
a track wdiose media data is accessed using a handle data 
reference.) In this case, w^hea the user decides to save the 
movie, our application framework code calls 
UpdateMovieResource instead of FlattenMovieData, 
UpdateMovieResource does not write any media data into the 
movie file; rather, it simply updates the movie atom, which 
contains the data references for each media. The updated 
movie file now' contains a handle data reference, The 
problem here is that, when the movie file is closed and then 
reopened, QuickTime won't be able to find the media data. 
The handle data reference, in all likelihood, no longer picks 
out any valid media data. 

Certainly one w^ay to avoid this problem is to make sure 
that we call FlatlenMovieData at least once before w^e close a 
movie file. But ihai might not be desirable in some instances. 
For example, our movie might contain references to other files, 
in addition to the references to memory-based data. We might 
not want to force all data references to be resolved, just one or 
two of them. 

A.S far as 1 know^, QuickTime doesn't curremly provide a 
way to flatten only selected tracks in a movie. We can work 
around this limitation, to some degree, by employing a simple 
technique invt>lving initialization extensions. The idea is to 
‘‘smuggle’' a track's media data into the movie atom, by 
attaching that data to the merlia's data reference as an 
initialization extension. When we then call 
UpdateMovieResource, the media data will be written to the 
movie file, since it now' forms pari of the movie atom. The 
movie file once again contains a handle data reference, but it’s 
harmle.ss; when QuickTime reopens the movie file, it will 
ntjtice the data reference extension and load the media data 
from that extension. Sweet. 

Its actually quite easy la implement this smuggling. We do 
it by passing a handle data reference to NewTrackMedia, just as 
we did at the end of the previous section. But this time, instead 
of pas.sing a handle data reference for a handle tc3 a O-lenglli 
block of data, w'e’ll pass a handle data reference for a NULL 
handle, w'here the handle data reference has an initialization 
extension. Let's begin by creating a handle data reference: 

myDaraRsf = NewHandle:Clear [slzeof (Handle) + sizeof (char)) ; 


Remember that a handle data reference Is a handle to a 
handle. Here weVe created a handle to a i-hyte block of 
memor}c all of w hose bytes are set to 0. Thi.s represents a NULL 
handle and a O-length filenaming extension. At this point, wee’ll 
tack on the atcim header for the initialization extension: 


kDataRefExtenslonlnitializationData); 
niyErr ” PtrAndHand (niyAtomHeadei:, myDataRef, 
slzeof {myAtcjtnHeader)); 

We haven’t actually added any initialization data to the data 
reference extension, only the 8-byte atom header. But that’s all 
w^e need at this point. We’re ready to call NewTrackMedia: 

TByHedia = NeirfTrackHedia (inyTrack, VideoMediaType, 
kVideoTlmeSeale. myDataRef, 

HandleDataHandlerSutiType}; 


When QuickTime sees the initialization extension atom 
header in the iiandle data reference, it know^s to keep the media 
data in die data reference itself, rather than in the memory' block 
addressed by the handle that forms the first four bytes of the 
data reference’s referring data. Tlie handle data handler is going 
to allocate whatever memory Is needed to hold the data we add 
to our media, so we can dispo.se of out data reference 
tmyDataRef) immediately if we like, 

Now^ we can edit the media and track as usual, for instance 
by calling AddMediaSample and InsertMedialritoTrack. When we 
.subsequently call UpdateMovieResource, the handle data handler 
wall write out a handle data reference w'ith a fully-configured 
initialization extension. 

Listing 13 show's most of this asseml>led into a single 
routine, QTDR_CreateTrackinRAM. It adds a new video track to a 
movie, with the track’s media data stored in ICAM. In addition, 
the media data will be written inio the data reference as an 
initialization extension when the movie atom is updated. 


Listing 13: Creating a track in memory 

QTDR_Crt;ateTr4ckiiiRAM 

OSErr QTDR_CreateTrac:kInKAH (Movie thsMovie) 

[ 


Track 

Media 

Handle 

unsigned long 
OSErr 


iflyTrack - MIX: 
myMedla - NULL: 
myDataRef ■ NULL: 
BtyAtomHeader [2]: 
nyErr = noErr: 


if {theMovie -- NULL) 
EretuentparamErr) : 


jnyDataRef = NewHandleClear{sizeof{Handle} + 

sizeof(char]}; 

if (niyDataRef “ NULL) 
return (MamErrejr C)) ■ 


myAtonjHeadet fOj = Eijdi 0 nU 32 _NtaB(sizeof (myAtomHeaderJ): 
inyAtouiHeader fl ] = EndiantJ32_NtDB ( 

kDataRafExtensionlnitiallzationUata}: 


myErr = PtrAndHand (myAtoniHeadGr. myDataRef, 
eizeoffmyAtomHeaderJ): 
if CmyErr t= noErr) 
goto bail: 

// cruiEtc rhe movk imck and media 
aiyTreok = Neiidiovi eT rack (theMo vie, 

FixRatio(kVideoTtackWidth. 1). 
FixRatioikVideoTrackHelahtH 1). kNoVolume): 
myErr = GetMoviesErrorO : 

If (myErr 1= tioErr) 
goto bail; 


nyAtomHeader [0] = EndiantJ32_NtoB (sizeof (myAtomHeader)); 
myAtomHeader [1] = EndiantJ32_Ntol ( 


myHedla = NewTrackMedia(myTrack* VideoHediaType, 
kVideoTimeScale. myDataRef, 
HandleDataHandlerSubType]: 
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rayErr = GetHoviesError(); 

if (niyErr 1= noErr) 
goto bail; 

// create the media samples 

myErr = BegitiMediaEditsCiDyMedia) : 

if (tayErr 1= noErr) 
goto bail: 

myErr = QTDR_A(ldVideoSaTiiplesToMedia (ray Media ♦ 
kVideoTrackWidtb. kVldeoTrackHeight); 

if (tnyErr != noEtr) 
goto bail; 

tnyErr = EndMediaEdlts (myMedla); 

If (myErr != noErr) 
goto bail; 

// add the media to the track 

ntyErr -= lusertMedialntoTrack (myTrack* 0, G. 
GetMedlaDuration(inyMedia) . fixed 1) : 

bail: 

if (myDataRef 1= NULL) 

DisposeHandle(rayDataRef); 

return(]DyErr) ; 

i 

This is a neat technique, liut it’s got a few limitations that 
you should know about. First of all, it works only with 
QuickTime 4.0 and later Under earlier versions of QuickTime, 
data reference extensions are simply ignored. Also, and more 
importantly, because the initialization extension is stored inside 
the movie atom, you should avoid creating very large 
extensions, 'the extensions will remain in R.\JV1 for significant 
periods of time, so it’s good to keep them small. 

Conclusion 

Data. We’ve gotta have it, at least if we want to do anydihing 
very interesting in our QuickTime movies. In this article, we’ve 
Uiken a look at a couple of useful ways of managing a movie's 
media data. First, we saw how^ to construct a movie that picks 
out its media data using media sample references. Tliese 
references can refer to existing data that lives outside the movie 
file (as in tlie case of our slide show^ movie) or tliai is already 
contained in the movie file (as in the c’ase of our effects movie). 
A sample reference is simply a way to make use of some 
existing data without having to copy it into a movie file or 
betw'een tmeks. 

WeVe also seen, however, that it’s sometimes useful to 
be able to go in the reverse direction, by forcing a movie's 
media data to be packed into an existing movie file. (At the 
very least, this makes it much easier to move the movie file 
around, since we don’t need to worry about moving any 
other files that the movie depends upon.) Our standard 
means of doing this is to call FlattenMovieData, but sometimes 
that either doesn’t work at all (as in the case of child movies) 
or doesn't work selectively enough for our purposes (as in 
the case of a single memory-based track). To work around 
some of the limitations of FlattenMovieData, w^e can use 
initialization data data reference extensions to attach media 
data directly to a data reference. 
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STARTED 


by Dave Mark 


Getting Started: Circa 2002 


I have to tell you, it feels great to be back. It's been a little 
more than five years since my last Getting Started column, hut it 
feels like an eternity. The long and winding road from the days 
of !mide Macintosh, Nubus cards, black and white monitors, 
GetPortO and SetPortCJ, trap patching, 68K emulation, etc. has 
turned a radical new corner. 

Though the vast majority of all Macs still run System 9 or 
earlier, the future is clear. This is a tmicjue moment in time and 
you have a unique (jppcirtunity. Back in the frontier days of 
Macintosh development, an unusual mix of elements was 
taking shape. There w-as u wonderful new computing platform 
that freed you from the traditional bonds of l>OS, Instead of a 
limited (and frequently cr>^ptic) .set of commands that governed 
your interaction with your computer, applicaticms .such as 
MacWrite and MacPaint allowed you ro expre.ss yourself in 
revolutionary new ways. 

As with any revolutionary change, opponimities blossomed. 
People loved the Macintosh and, as word spread, their hunger 
for new^ applications grew dramatically. Problem was, 
developing a Mac applkaiion was cotiipletely different than the 
relatively simple proces,s of building a DOS or Unix app. Back 
in the day. Inside Machtiosh w^as a single volume tliLii came in a 
lcx)se leaf binder, and dedphering its mysteries required 
dedication and a great deal of trial and ernjr. But, for tliose ^in 
the know”, there was money to be [iiade. Startups were 
everywhere. This was fertile ground. Excitijig dines. 

I loved those early days. The excitemeni of learning al)out 
something so new and so l>eautifully crafted insf^ired me. And 
tmce I understood die basics, 1 felt compelled to share my 
knowledge with the Mac development community. 1 WTOte 
bcK)k,s like the Macintosb Frogmfnminjj Primer series. Learn C 
on the Macintosh and, of course, 7 years worth of Cletting Started 
columns for MacTech. 

Over time, each new release of the Mac OS hroughl less 
dramatic changes and the process moved from revolutionary 
to evolutionary. A.s the process of building a Mac application 
became less mystical and more practical, money came to the 
table and getting a Mac application to market and competing 
with established brands became harder and much more 


expensive. What was once a fun, "programming for die beauty 
of it" process moved from the computer science end of the 
spectrum to the marketing end of the spectrum. The pioneer 
days were dead. 

And now weVe come full circle. Mac OS X Is a wdiole 
new beast. New' APIs to learn, a new development 
environment to explore, new widgeUs to play around with. 
We've got a whole new frontier to explore and there are 
opportunities here for all of us. 

Getting Started 

There are a numlx^r of paths to explore here. Well start with 
the most straiglitforward, building an app using the Objective C 
prog lamming language and Apple's Cocoa framework. Over the 
coming montlis, well dig into die iiasics of Objective C. Over 
time, wee’ll take on Cocoa and, eventually, explore some of the 
other paths to build our Mac OS X apps. Td also like to spend 
some time under the hood, exploring the OS upon which Mac 
OS X is based, Apple's port of the Unix operating system. 

Go get the tools 

There are a numiier of good choices out there when it 
come,s to development tools. There’s Code Warrior from 
Metrowerks, KHALbasic from RHAL Software, a variety of 
AppleScript environments, and many others, Kor the moment, 
were going to focus our attention on the tools that Apple 
provides, gratis, to ensure we all start on the same footing. 

When Apple boughi NeXT hack in December of '96, they got Stet^ 
Jobs hack and they also got SteiKTs OS and the dewlopment tools 
crafted to imrk alongside the OS, The OS evoked into Mac OS X, 
and the tools fiecame Apple's official Mac OS X dev tctols. 

Many of you already Ivave Apple’s dev tools in hand. Newer 
Macs ship w'ith a Developer Tools CD. You may find diat your 
Mac came w ith the tools pre-installed. Nonetheless, go through 
the W'eb .site, dowmload the latest and greatest, and install them 
on your machine. 


Dave Mark is very old. He’s been hanging around with Apple since before there was electricity and has written a number of btxjks on .Macintosh 
development, including Learn C on the Macintosh, Learn C++ on the Macintosh, and The Macintcxsli Prognimming Primer series, Dave maintains a 
primitive web site at hnp^ 7www.spidei-works.com 
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First step: Navigate to^ 

http://developer.apple.com 

This is the home for the Apple Developer Connection, also 
known as ADC. There is a ton of great ntaterial on this site. You 
can sign up for Apple's various developer programs, including 
the Premier (US$3500 per year), Select (US$50Q per year), 
Smdent (.US$99 per year ), Mailing {US$199 per year), and Online 
(FREE) prograins. Take .some time to go through the program 
descriptions to see if one of them is right for you. 

To get die tcxds, all you have to do is register for the Online 
program. To register, send your browser to: 

http://connect.apple.com 

Click the "Join" button, read the license, click “Agree^, then 
fill out the fortn and select your new Apple fD. Once your 
account is set up, log in, then select Download Software frc^m 
tlie nav bar on the left hand side of the ADC window. Next, click 
Mac OS X from the sub-nav bar iFigure II 

Manage Assets 
Purchase 
View ADC TV 
Review History 
Downtoad Software 
Audio 

Docurnentation 

Java 

Mac 

OpenGw 

QuickTim 

WebObiects 

WWDC2002 

Update Profile 
Log Out 

Figure 1, Click the Dimntioad Software Ihtk theti Mac OS X 

There are a lot of choices on this page. As 1 write this, the 
latest releases are the /ii/y 2002 jMac OS X 10.2 DeielolK^r 7(x2s 
and the August 2002 Deu Tools JOJ UjMlate. Hy the time this 
column gets to you, however, there may be a new release of the 
tools or another update. As a rule, download the most recent 
Developer Tools package first. Then, check to see if an (pdate 
package was released after the DewlalxT Tools package. If so, 
download it as well. Install the Dei^hper Tools package and the 
Update^ if applicable. 

Checking the Install 

Once the tools ^ire installed, you should have a directory 
named Develcjper at the top level of your hard drive. My 
Developer directory listing is shown in Figure 2. Take a few 
moments to go dirough the various Developer sub-directories. 


9 0 0 Developer 



iack Forward View 


9 items, 11,44 CB available 

► £1 Applications 

► U Documentation 

► £31 Examples 

► ^ Headers 

► pjava 

► ^ Makefiles 

► P Palettes 

>■ P ProjectSuilder Extras 

► P Tools 

figure 2. 77je Deieloper dtrector\f after the tools install. 

In the Applications directory*, you'll Find a number of 
inlere.sting tc.K)ls, inciLiding one we ll fire up in just a sec called 
Froject Builder. For you Code Warrior fans, Project Builder is sort 
of the equivalent of the CodeWarrior IDE, a command central 
fur all your project file.s anti the ajiplicatinn that actually calls the 
compiler and other coile building tcx)ls. 

I'he Documentation folder is alsti filled with important 
goodies. Get to know wiiat docs are available. There's a lot of 
good reading in there, and iFs all free. One short file wxjith 
reading is the RFADMK.html file in the Documentation directory^ 
This file will open in your web browser and lists various ways 
to access the documentation from within Project Builder. 

If yoiFd like to get ahead of the game, rake a look at the 

file; 

/Developer/Documentation/Cocoa/ObjeaiveC/ObjC.pdf 

ObjC.pdf will give you a fairly thort)iigh grounding in the 
Objective C language. 

Take *em For a Spin 

Now' diat the tools arc installed, let's take them for a spin. 
This mt>nthN prtjject will be a simple C "Hello World" project, 
just to gel a sense of the environment. Next inontli, well try our 
hand at some Objective C code. 

Navigate intcj the /Developer/Applications folder and 
launch Project Builder, Select New Project... from the File menu. 
The New Project dialog appears, allowing you to specify the 
type of project you'd like to build. Scroll all the w^ay to the 
bottom and select Standard Tool (Figure 3). Standard Tool 
builds an ANSI C command line program. Click the Next button. 


48 


Getting vSt.4rted: Circa 2002 


MAdTECH • November 2002 















Ever consider exhibiting at MacWorld? 
Thought it might break your budget? 

THII\IK AGAIIU! 

The most affordable solutions. Completely turnkey. 

9 Pavilions to Choose From: 


Bluetooth & Wireless 
Technologies 
Enterprise, Networking 
& Server Solutions 
Education, Edutainment 
& Assistive Technologies 


• MacTech Central 

• Digital Media 

• QuickTime 

• Internationai 

• SciTech Pavilion 

• Business Solutions 


LIMITED TIME SPECIAL DISCOUNT OFFER: 
Get $ 1000 off your station package! 

If you sign up by October 3 h 2002, you 7/ gef US$1000 off 
your station, bringing the price to just US$2995! 

Send e-mail or visit the pavillion web site for more details^ 

reservations@xpiaiii.<om 
http:/ / www.xplain.com / macworldexpo 

805/494-9797 


Xplain Corporation * PO Box 5200 • 850‘P Hampshire Road • Westlake Village, CA 91359-5200 
Voice: 805-494-9797 • Fax; 805-494-9798 • reservations@xplam.com 





Conferences January 6 -10,2003 
Expo January 7-10,2003 
San Francisco The Moscone Center 


macworldexpo.com January 6-10 


Macworld 

Conference & Expo. 



Macworld Conference & Expo is recognized as the''must‘attend" 
event for the Mac community. Join tens-of-thousands of attendees 
this January to benefit from high-level education and enjoy 
the strong community and camaraderie that takes place at this 
all-in-one marketplace. 

"The best single source for information on the Mac. Even Windows users 
would be enlightened." 

President 


"if you use a Mac, you are not using it to its fullest potential until after 
you attend Macworld." 

Graphic Artist 


WIDG 

WORLD EXPO 


flagship Sponsors Platlnunn Sponsor 

Macworld Macworld.coin % Mac central COTiEL 









Acquire what you need (knowledge, products, 
services or solutions) to stay competitive and on the cusp 
of technology. 

Enjoy the one-stop-shop atmosphere only Macworld 
Conference & Expo can provide you. 

Test drive brand new products and services — 
be one of the first to kick the tires of the latest innovations. 


Network, exchange ideas and build contacts with 
like-minded, or not so like-minded, users and industry gurus. 

Feel what it is like to be part of a loyal, powerful and 
holistic community. 

Discuss your issues, mention your concerns, or praise 
the manufacturers of yourftvorite products directly. 


Apply knowledge learned from 5 intense educational 
days at Macworld Conference & Expo immediately. 


Register online with Priority Code: A-MTN 

For more information, call toll free 1-800-645-E){PO 


























o NfWfTO>fH 


! 



Figure 3- Select the Standard Tool project template. 

You'll i^e prompted for a directory in which to store all the 
project related files (Figure 4), including all source, object, and 
binaries. Name your project Hello World, then click the 
Choose... button to browse on your hard drive for a location for 
the Hello Wbrld folder. I created a Projects folder witliin my 
personal folder rather than storing the projects witliin the 
/Developer directory, I don*! want to wipe out my projects when 
1 decide to do a wipe and reinstall of the dev !ot>ls. 



Figure 4. Smnng )four neu^projM Jtles, 

Now click the Finish button. Project Builder will build a project 
for you, complete witli a source code file named main.c 
containing a niainO function any C programmer will recognize 
in a heartbeat. 

The project window that appears contains a numlier of 
elements. We'll get into them in detail in next montli s column. 
For now, the important elements are the “Croups tk Files'’ pane, 
the code editing pane, and the toolbar (at the top of the 
window, the one wath all the funny hammer icons). 

In the “Groups 8c Files'' pane, click on tlie disclosure triangle 
to the left of the Source folder ict^n, You1l reveal a single tile 
named main.c within the Source group. Click on main.c. Notice 
tile source c(xle that appears in the code editing pane t Figure 5). 



Figure 5 The Hello World source code listed in the project 
wmdotv's code editing pane. 


Let's run this sucker. Click on the 3^^ icon in the toolbar 
(the one with the hammer covered by a computer display). If 
you hover over the icon, a tooltip appears with the words “Build 
and run active executable", Thafs the one we want. This will 
compile our ,source, link our object code into an executable and 
mn the executable. Do it. 

Your result should be eerily similar to the one shown in 
Figure 6. Cool! 

A©.e _ _Hello World - mtm World}_ CD 

n I lT\ rHgilo^W^ld Tj 

ticLnld hM liltb 0 . 


I 


Hello World wiUd noriTLellv. ^ 

Figure 6 , Hello World ckm Its thing. 

When you asked Project Builder to build and run your 
project. Project Builder did just that. If you click in the Window 
menu, you1I ,see three ,subdiems under the “Hello World - (Hello 
Work!)" item. The one selected in Figure 7 is the Build window. 
Under that is the Project window (in this case, listing the main.c 
source code). Under dial is the Hun window .showing tlie output 
of the program executic}n. 

l 44 ni tVln^lEiw 

wifiJw 
trlfli JUI In FrwH 

tWIiithirid IWijirPl_ 

H*Etp. Wkirld RiHrtc 
./ IHH. Warm - Woriift 

Figure 7 Project Builders Window menu. 

You can close any of these windows at any time, though 
you'll likely w-ant to keep the prt>ject window' open so you can 
make changes to your source code and build and run your app. 

Tiu, Next Month„. 

Want to play some more? Got^d! Try making some changes 
to the .source code. Got an old copy of Learn C on the Macintosh 
lying around? Try typing in some of Uiat source code. And if you 
are really adventuresome, lake the debugger for a spin. Hint: 
The tooltip for the icon from the left in the project window's 
toolbar says “Build and debug active executable”. 

Next monih, w'ell go through Project Builder in a bit more 
detail and go through the debugger as well. It's good to be back 
- Thanks for reading! 
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MAC 05 X 


By Andrew C. Stone 

The Ins and Outs of Drag and Drop 


Tlie most copied feature of the Mac OS X interface is the 
ubiquitous drag and drop. When NeXTStep advanced the 
techniques pioneered at Xeroxes PaJo Alio Research Center in the 
late '80’s, the way in w^hich people interacted with software was 
changed forever. The ability to move data and objects seamlessly 
between window^s and applicaiions without any additional steps 
is the hallmark of a native OS X application. This article will 
explore some more advanced techniques and some of die issues 
you might encounter when preparing your interface ft>r drag and 
drop, as covered in other MacTech articles, such as 
http://wvwv.stone.com/Tie_Cocoa_Files/What_a_Drag_.html. We'll cover 
making an entire window a receptacle for drag and drop, using 
central control to reduce code, dealing with temporary subviews 
such as field editors, and auto-swapping Tab views based on the 
type of data being dropfied. 

Many of Stone Design's applications fit into the category of 
'’just drag and drop and you’re done/' such as PStill, GlFfun, 
PackUpAndGo, DOCtor and SliceAndDice. I'aking PStill as an 
example, the user just drags a file onto the PStill window or 
application tile in the Dock or the Finder to convert the file to 
or redistill it as PDF^ 



The strategy I like to employ is to make the entire window 
a valid drag target by .subclassing NSWindow or NSPanel, and 
forwarding the actual methods to the window’s delegate; 

ginterface NSOb ject (impleiiient_thia_in_delegate) 

- Cvold)registerTypefiForPanel:(NSPanel *)panel; 

@etid 

iiaterface SDDi:agIrkPanel : NSPaael 

I I 

tend 

@iEiipleitientation SDDragInPanal 

- (void)awakeFron»Nib 
1 

[[self delegare] reglsterTypesForPati^ltself] : 

1 

- {unaigned itit) dragglngEntared: sender 
[ 

return [[aelf delegate] dragglngBiitered: sender] ; 

I 

- (unsigned int) draggingUpdated;sender 
( 

return [[self delegate] dragglngUpdated:sender] ; 

I 

' (BOOLJ prepareForDragOpetation;sender 

I 

return [[self delegate] 
prepareParDragOperation:sender]: 

1 

- (BOOL] perforaiDragOpEration j {id <NSDraggxngIn£o)} sender 
[ 

return [[self delegate] perforiuDragOperation;sender] : 

I 

@end 


H PSlIN Cnnverston TonU TcxtExtras Window Help H 



Drag files onto Dock or Window 


Typical code for delegate would be; 


// Dragging stuff: 

(WSArray *)acceptableDragTypesf 
rertirn [USArray 

arrayWithObjects sNSFllenamesPboardType,nil]; 

1 

- (void)registerTypesForPanel;(HSPanel *)panel; 
1 

[panel cEgisterFnrDraggedTypes;[self 
a c c ep tab 1 eDr a gTy p e a] ]: 

I 


- (nnalgtied int)draggingEnteredQrUpdated: (id 


Andrew Stone is founder, lamtor and chief computer sciennsr at Stt>ne Design, www.stone.com. 
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<NSDragginglTifo>) sender 1 
// we want to igoore drags originating in oitr own window: 

if ([sender draggingSource] ^ dragWellView) return 
t^SDragOperationNone: 
else I 

unsigned Int sourceMask = [sender 
draggingSourceOperationMask]; 

NSPastebaard 'pboard “ [sender draggingPasteboardJ; 
NSString *type = [pboard 

availableTypeProntArray: [self acceptableDragTypes] ]; 

If (type) return sourceMask: 
return btSDragOperatlonNone: 

I 

] 


MARX"’CRYPTO-BOX USB 

Security Key For Macintosh 

Use the CRYPTO-BOX®USB to secure data, 
networks, or software from unauthorized use. 


- (unsigned intjdraggingEntered:(id <NSDragglngrnfo>lsender 
( 

return [self dragglngEnteredOrUpdated;sender] : 

I 

' (unsigned int)draggingUpdated:(id <NSDraggingIiifo>)sender 

[ 

return [self draggingEnteredOrUpdated:sender]; 

J 

- [BOODperformDragOperation: (id <NSDraggingInfo>)sender 

f 

NSPasteboard ‘pboard = [sender draggingPastehoatd]: 
HSString *type = [pboard avallableTypeFrotEiArray: [self 
acceptableDragTypes]I; 

BOOL loaded = NO: 

Id ts - nil: 
if (type) { 

if ([type isBqualToStringiNSFilenamesPboardTypel) I 
NSArtay *files = [pboard 
propertyListForTypeiNSFilenainesPboardType] : 

unsigned i = [files count]: 
vbile (i- > 0) [ 

NSString *f = [files objectAtlndex:1]: 
if ([[self acceptableFileTypes] 
contaiusObject: [f pathLExtensiQu] ] && (ts “ [SomeObject 
objectWithContentflOfFile:f]) j 

loaded YES: 

break: 

I 

1 

] 

) 

return loaded: 

] 



Supports ail Macintosh Systems with USB including 
OS 8.6-9.1, & MAC OS X (CFM, Mach-0, and apps 
in classic), Windows in MAC OS 9 and Virtual PC 4. 
Metrowerks CodeWarrior C/C++ and Apple Project 
Builder C/C++ samples available 

Contact www.nriarx.com 


- (BOOL) prepareFo rDragOper at ion: sender 

f 

return YES: 

I 

Be sure to register the view for the accepted types.A good place to do this is in - 
(vc>id)awakeFroraNib.This method is called on any object instantiated in a NIB (NeXT 
Interface Builder) file that has an Implenientation of awakeFPomMb after all the objects 
are created and linked up, but before tlie window appears on screen. By implementing 
a single method acceptabJcDragTypes that returns which types you actually accept, you 
can avoid out-of-synch cijde when you add more types to open later 

[panel registerForDraggedTypes;[self 
acceptableDragTypes]]; 


MARX Software Security 

2900 Chamblee-Tucker Road N.E., Bldg. 9 
Atlanta, GA 30341, USA 

* 1-800-MARX-INT 

* 1-770-986-8887 
fax 1-770-986-8891 
info@marx.com 


So we are done, right? Not quite, because of the way 
NSTextFields work. When you ciick or tab into a text held, a 
shared NSTextView is inserted into the view hierarchy. When the 
user drags a file over any part of the window that doesn't have 
an active textfieid, the draggingEntered works as planned. But 
when you pass over the active text held, the NSTextView's drag 
validation methods come into play. The solution is to subclass 
NSTextView to also forward the methods to your window's 
delegate ^ or just to the window, since the window will forward 
on to the delegate: 


MARX Software Security GmbH 

Vohburger Strasse 68 
D-85104 Wackerstein 
Germany 

* (+49) 8403/9295-0 
fax (+49) 8403/1500 
contact-de@marx.com 
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Track 


-Vv 


IJ 


Keep track of every second of your time and bill 
for it with Time Track! Built in instructions make 
it easy to use. It is a simple way to manage your 
billable time for multiple projects and create a 
web page to show to your clients. Only $24.95 
per single user license per platform. Finally! A 
versatile time tracking solution for Macintosh, 
Windows, and Polml 


www.frinfmitysoftware,com 



Eudofa Internet Moil Server (EIMS) 
3.1 is the latest version of the most 
popular Internet mail server for the 
Macintosh. If you need to handle 
email for a dozen users, or 
thousands of users, EIMS is a 
reliable and easy to use solution. 


EIMS 3.1 is available for IJSS40Q.OO, there are no limits on the number of users 
that can be added, and free email support is included. 


for more inhrmotion, see 

http://www,euclora,co,nz/ 



GraphicConverter converts 
pictures to different 
formats. Also it contains 
many useful features for 
picture manipulation. 


See wwwJemfcesoff.com 

for more information. 


Suite Deal 


A suite of must-have 
utilities for Mac OS X 
$170 value for $49.99 



for X cleliverrs fill ly* registered favoritc.s 
in one convenient package at one great 
price. Plus, OS X tips fh>in the pros and 
dozens of trial versions from top-names like 
Adobe and Micrt>safl are included FREE! 
Visit v%Tvw*aladdinsys,cain/tcnforx 



WWW', tie vde pot. com 


Ten for 




Alarm Clock 5.E, 
ExecytiveSync 
FruttMeny 
iCIean 
ideaSpiral X 
LaunchBar 
Limewire Pro 
piPop 
Pseudo 
PrintMagk X 
WindowShade X 
Xounds 




Aladdih 

Systems' 


AlaOdfn products are available from your favorite Mac dealer or catalog and at shop.aladdinsvs.coffl 

www.alaelclinsvs,com • www.StuffIt.com • www.TenforX.coni 

■Copiyilght D2(KU. Aladdin Systtflli, im:. All rlghtt resjewed Tert to X Is a tradenlaf ks of Ataddin IncLliE Aladdin Logo ft ■ reglstcnd tfadetnark Crf Atflddin Inc. Other brand and 

pr^ltCt rumes art the [radsmadci or negistered trademarlis of their respective owneirs. 
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Watson 1.5 

Winner of the 2002 Apple Design Award for Most 
Innovative Mac OS X Product! An Aqua experience 
for the most useful Web services: TV & Movie Listings, 
Reference, Translation, Stocks, Flights, Package 
Tracking, and more. With an open architecture for 
third-party tools as well. Download the demo now! 

www.karelia.com/watson 



By TLA Systems 

The Dock with more than one dimension. 

Create multiple docks of any size, assign hot keys and 
even put the Trash back on the Desktop. A flexible and 
feature-laden tool for power-users. Runs natively on Mac 
OS X and 9 in five languages. 

“...you made ibe swikb to OS X a tot easier for me...^- Sob LeVitm 

‘LOragJbmg con rigbtfuBy be called an iadhpemabk aid to working with yam 
Mac..“^li^Q(UserUK 

Download a copy now from www.dragtliing.com. 



Trapcode * piug-tns for Adobe® After Effects® 

Trapcode Shine is a fast light effect plug-in. The effect looks 
very much like volumetric light, but is actually o 2D effect. 
There are special controls to make shimmering lights and 
numerous coloring modes. This is an effect that you see 
everyday on TV and in many movie titles. Shine is available 
for Mac, Mac OSX and Windows. 


WWW. f rapcocte.com 





Got a great product sold through Kagi? 

Promote your product through the very cost 
effective Kagi Showcase in MocTech Magazine. 

For more information, contact us at 

adsales@mactech.com 
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IPHetmonitorK 

• The Swiss Army Knife of Klac OS K 
internet Diagnostic Tools 

• 15 FuUy integrated Tools- 
monitor, Link Rate, Address Scan, 

TCP Dump and more 

• Troubieshoot and Soiue iletuiorh Problems 

• Responsiue, intuitiue, Easy to Use interface 

• Fast multi-Threaded ArchRecture- 
see network behauior as it happens 

• 21-Day Fuily Functional Free Trial 


^import <Cocoa/Cocoa*h> 

^interface DragTextView : NSTextVlew 

I 

] 

@end 

^Hmport "DragTextView.h" 

^implementation DragTextView 
// override drag stuff.., 

- (id}initWithFraii]e;CNSRect)r 

[super initWith¥ranie: r] : 

[self tegisterForDraggedTypes:[[[self vindow] delegate] 
accaptableDragTypes]]; 

if this is so TAR and RETLIRN end editing 
if instead of l^eing inserted into the field: 

[self setFieldEdltor:YES]: 
return self: 

) 

// note we |ust pa.'iS it up to the window; 

' (unsigned int) draggingEntered:sender 
( 

return [[self window] draggingEntered:sender] : 


etc, Just passing on the method to the window 


(Send 


Now we have our cuslom lext view, liut how do we 
make .sure our text view is used in place of the standard lexi 
view? We can^t set z in Interface [Guilder, but we can code it. 
If a window's delegate implements a method called - 
windowWillKeturnlueldEditordNSWindow *)sender 

toObject:(id)c]ient, the Appkit code will call this method and 
use rhe text view it returns if non-nil, otherwise it uses a 
standard text view set in field editor mode.) 

// add ttxtVinrV as an iV:ir to tirr NSWindowCiHitrollcr subclass which conuols die 
wind{>w 

(id)windowWiliReturnFieldEditor:(HSWindow ')sender 
toObject:(id)clienr f 

if [sender = [self window]) I 

if (ttextVlew) textView = [ jDragTextView 
alloc] inltWithFraine; (ntyField bounds] ] : 
return textView: 

I 

tEturn nil: 



Download Your Copy Dow at 

www.sustworks.com/mac 


SUSTAINABLE 




At this point, our interihee is ready to accept the correct files 
and data at any IcKaiion in the window. 

There's one final issue: what if a user can drag a file out of 
your interface (for example, in PStill, yoLi can drag the distilled 
PDF file oul of the "drag out well") and that File type can also be 
dragged in to I he application (for example, PStill accepts PDF 
files as input). A user might start a drag t>ut of the application, 
change lier mind, and drop the file back onto the application 
window. In this case, the application should probably not 
process the file. Therefore, the window delegate should check 
the draggingSource to make sure it's not a component of the 
window itself. This is why we have this line in the 
draggingEnteredOrUpdared code above: 

if [[sender draggingSource] ^ diagWellView) return 
HSDragOperationNone: 
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Aiitoswapping Tab Views 

The concept of filtering the dra.gging methods through the 
window's delegate can be very useful when your window 
contains an NSTabView witli different acceptable types in each 
view. In Create®, for example, there is a resources library which 
can accept ait, images, effects, blends, patterns and pages: 

^ Creat€ File Edit Format Fom Web Object 



Create® lets ymi siore many different types of resources -and it 
Will swap to the correct tab view as necessary 

Each of these tabviews has an NSScrollView, which contains 
an NSMairix. When a user drags in a certain type that is not 
correct for the current view, but is acceptable in another one of 
the lab views, the tab view should automatically switch to the 
otlier view so that the drag can drop successfully in tlie right 
place. We do hiis by first checking if we can deal with it ^ and 
if not, well ask tlie window^ controller (which keeps track of the 
other views) to check the other resource managers. Note we also 
don't want to accept drags that start from this particular 
resource's matrix: 

- (unsigned int) draggingEntered: (id <NSDi:aggiTigTnfQ>) sender 

I 

return [self draggingEnteredOrtTpdated:sender 
checkOthers^YES] ; 

1 

- (unsigned intidraggingUpdated:(id <NSDraggingInfo))Bender 
( 

return [self draggingEnteredOrUpdated:sender 
checkOthers:YES]: 

1 


PrimeBase 4.0 

M g w 

Launcher for OS X 



Installation has never been easier on 
Mac OS X with the PrimeBase Launcher 

Download the Launcher now 
and get started with PrimeBase 

www.primebase.com 



,eve»oper Keys 

avaWab'c 

tree o1 charge 



PrimeBase Database Server and 
PrimeBase Application Server 

AVAILABLE ON THE MOST POPULAR PLATFORMS 

• Completely cross^platform 

• Full-text searching and indexing 

• Mac OS classic & X 

• Mac OS X Server 

• Unux 

• Solaris 

• IBMAIX 

• all Windows platforms 

Develop on a Mac and deploy without any 
additional effort on any platfonn you want 




PrimeBase 


- (unsigned intJdraggingEnteredOrUpdated:(id 
<NSDraggiiigInfo>)sender checkOthers:(BOOL)checkOthers 

t 

if ([sender draggingSource] = dragMatrix) return 
NSDragOpGratlDnfJone: 
else I 

HSPasteboard ‘pboard - [sender draggingPaateboard] ; 
tiSString ‘type = [pboard 

avallableTypeFromArray:[self acceptableDraggedTypesl ]: 


SNAP Innovation GmbH 
Altonaer PoststraRe 9a 
D-22767 Hamburg / Germany 
WWW. pr i mebase.com 
e-mail: info@primebase.com 
Fon: ++49 (40) 389 044-0 
Fax: ++49 (40) 389 044-44 
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if (type) I 

unsigned int sourceMask ^ [sender 
draggingSourceOperationMask] : 

if ([type 

isEqualToStringiHSFilenaffiesP'boardlType] ] 1 

NSArray ’filenaTnes = [pboard 
propertyListForTypeiKSFilenajnesPboardType ]; 

if ((filenames count] ^1] t 

NSString 'filename = [filenames 

objeGtAtIndex:0]; 

if ([ [ [self resourceClass] fileTypes] 

containsObject: 

[filename pathExtension]]) 

return aourceMaak; 

[ 

1 else return sourceMask; 


I 

if (checkOthers) return [_controller 
draggingEnteredOrUpdated;sender]; 

else return MSDragOperatlcmNone: 


The ^controller's implementation might look someiliing like 

this: 

- (unsigned intjdraggingEnteredOrllpdated; (id 
<NSDragginglnfo>)sender 
f 

int i, c = [_resciurceSources count]; 
unsigned int returnValue: 
for (1 “ 0 ; i < c; i'H-) f 

ResourceSource ^res = LresourceSources 
objectAtIndex;1]: 

if [res “ _currentSource) continue: //iitody checked’ 
if ((returnValue = [res 

draggingEnteredOrUpdated:sender checkOthers:NO]) 1“ 
NSDragOperationMonej I 

[self showRescuroeSourceNamed:[res 
resourceSourceMatnei ] ; 

return returnValue; 


return MSDragOperationNone; 

1 

(void)showResourceSourceMamed:(NSString *]name 
f 

[tabVlev selectTabViewltemAtlndex;[tabView 
indexOfTahViewltemWithldentifier;name I]: 

I 


Because the matrix may not fill the scroll view entirely, we’ll 
also have to subclass the scroll view to foi-w'ard draggingEntered 
ineihods to tlie matrix. To the end user, the entire sera! I view is 
seen as the target, not just the matrixE 

- [unsigned intJdragglngEntered:(id <NSDragginglnfo>)sender 
[ 

return [[self docutnentView] d raggingEntered ; sender] ; 

... etc for all the other metlusds. 


AppiJCAiroN Tile Dracx Support 

You only have to perform a few tasks to add support for 
drag and drop to your Application icon and its Dock tile. First, 
you'll need to alert the system of the valid file types handled by 
your application. Then, you'll implement a method in the 
Application's delegate subclass which calls the actual method to 


deal with that file type. 

First, add information about w^hich files can be opened by 
your application in Project Builder^s application Target Inspector, 
in the "Document Types” pane: 



Z?e strre k> add the file types that ymtr application can o^)en in 
Project Builder 


Second, set your application's delegate. You can do this 
programmatically with NSAp plica lion's .seiDelegate:. Or, you can 
use Interface Builder: (a) instantiate an object of your delegate 
class in your main NIB tile, and (b) connect the File's Owner 
instance variable "delegate” to ihi.s new^ object. 

I hird, implement a single method in your delegate's class: 

- (BOOL]application;(NEApplication ')sender 
openFile;(NSStriug ‘)path 

i 

MyDocument 'doc = ([NSDocumentController 
sha red DocunieTit Control let] apeuDocuiLGOtWithContentsOfFile; path 
display:YES]: 
return doc: 

] 


Now, not only wall tlie dock tile accept drag and drop, but 
Finder will display your application as a choice for opening drat 
kind of document. 


Conclusion 

If you want your application to really sing, be sure users 
can take full advantage of drag and drop everywhere! Not only 
wall it make program interaction easier and more fun, it makes 
demoing the app more speetaeularl 
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New OS. New Software. New Installer. 


Introducing Install Anywhere - Mac OS X Edition, the new power tool for your Mac OS X software 
installation. Stop using yesterday's tired old installer tools. Now, you can create industrial strength 
installers that are flexible, intuitive, and royalty-free. Your software will look better than ever and 
install perfectly, every time. 

Install Anywhere supports all Mac OS X features, like user authentication, file permissions, installing 
icons into the Dock, and offers a fully customizable Aqua look and feel. 

Software innovators like Adobe, Apple, Borland, Gracion, LimeWire, and Sun already depend on Zero G 
for their software installation needs. See for yourself why InstallAnywhere - Mac OS X Edition is the new 
power tool for your software. 


fnstallAnywhere - The Industrial Strength Installer From Zero G. 

Download a free trial version from http://www.ZeroG.com/goto/mac 



©2IKIZ 2m G Software, Inc. InstallAnywhere and Zero G are trademarlta or reiisiered trademarks of Zero G Inc. Mac Is a tradeniark of Apple Computer, Inc., reii^tererl in the li.S. 

and other cojntries. The 'Built for Mac OS X" graphic is a trademarli of Apple Computer inc., used under liceitse. All other trademarks are property of thair rispecthre ownar^. 
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COMDEX Fall 2002 is your best opportunity to experience, 
explore, and learn about the latest product innovations, 
leading vendors, and powerful new business strategies. 


FREE access to the exhibit floor 

c.. 

FREE entrance to the Great Debates and Hot Spots 

53'- 

FREE admission to the new Digital Lifestyles Conference and SuperSession j 
Content-rich Educational Programs for business and technical professionals 




gister today! 






i 


Visit wwwxomdex.com/faU to register or call 888-568-7510. 
Use Priority Code HCMG and Coupon Code 342. 


PRESENTS 


FALL 200;^ 
~ . THE GLOBAL TECHNOLOGY MARKETPLACE 

■SM 




OFFICIAL CORPORATE SPONSORS OF KEY3MEDIA GROUP 






rnrd 





■NYSE 

New VcKrk ^llsck ElDcbiUlge. 


CopyHeht © 5002 Key^MedFa Events, lnc,» 5700 Wll^hire Boulevard* StiiLe 315. Los Afiieles, CA 90036-3659. All Rights Reserved. C0 d 2-12171 io/tJ 3 Key^Wedte, COMDEX, and associated design marks and 
logos are trademarks owned or used under license by Key3Media Events, In^.. and may be registered in the Untied Steles and other couilrles. Other tiatties menUoned may be trademarks of theli respective owners* 






Conference Overview 

Make the most of your COMDEX experience 
with our offordable Cducationat Programs. 


COMDEX Educational Programs keep you at the 
forefront of technology and are designed to 
provide the specific information and strategies 
you need to maximize the return on your 
technology investments. 

Business Technology Conference 

Acquire in-depth information on key technologies, essential business 
strategies, and action-oriented solutions to pressing IT issues such as ROl, 
security, Web services, wireless, storage* business continuity* and project 
management. 


TechCentric Conference 

Get innovative solutions for today’s critical development challenges, explore 
new tools, and learn about the latest network and infrastructure technologies. 


Real-Time Enterprise Conference 

Discover how ERP, CRM, SfA, procurement, logistics, and supply chain 
databases can come together to create new ways to link critical business 
systems, deploy technology* and empower the workforce. 


The COMDEX IT Executiv e Sympos ium, 

presented in partnership with 

Hear from visionary technologists* innovative companies* and executive 
practitioners who are reconciling the euphoria of the past with the real-world 
pragmatism of the present to make breakthrough technologies pay off. 


FORTUNE Small Business Forum 

This survival guide will enable small businesses to use the Web to crack 
new markets* generate sales* and develop winning marketing strategies. 


All Conference registrants receive FREE access to 
the Exhibits, VIP seating at Keynotes, Great Debates, 
ZDNet Unplugged Interview, and the Digital Lifestyles 
Conference, plus a COMDEX conference bag. 



Keynotes- Free to alt COMOex attendees 



PETER CHERNIIi 

News Corporation and 
Fox Group 



BRiAN HALLA 

National Seiniconductor 



CARLOS BONILU 

National Economic 



STEPHEN WOLFRAIH 

WoEfram Research 


Gain full access 
with a Flex Pass. 


Be sure to check out our complete Conference* 
Tutorial, and Certification schedule at 

www.coniidex.com/faU. 


Enjoy the flexibility of attending 
any of the COMDEX Educational 
Programs—including alt of the 
COMDEX Conferences and Tutorials. 
(Does not include Microsoft and 
Cisco Professional IT Certifications.) 
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COCOA 

DEVELOPMENT 


By Dan Wood, Alameda CA 



Table Techniques Taught Tastefully (part 3) 


Using NSTableView for Real-World 
Applications 


Introduction 

ThLs is the last of a series of articles ahoul the wonderful 
NSTableView class in Cocoa. While the first part went over the 
basics, and part the seccmd goi your hands dirty, this last part is 
where we pull out all the stops and dtj some really tx)ol ihin^s 
with tables that will make you the envy of al! the Cocoa 
programmers on your block. 

in this article, we'll show you how to give your tables those 
trendy blue and w'hite alternating stripes and vertical grid-lines 
that you see on programs like iTunes. Well make a subclass of 
NSTableView that merges cenain cells together across multiple 
columns, suitable for display of a time scliedule. We'll make a 
custt>m cell to indicate relevance, like you see wlien you search 
in Apple’s Mail program or the Finder. And finally, we'll see 
how to animate the sorting of a table, like you see in iCdiaU 
(Warning: There will be math in the last segment!) 

Ue sure to follow along with the ''TableTesfer* application 
(downloadable at www.karelia.com/tableTesTef/), a program 
show ing off most of the table Features described in this series. It 
contains the source code corresponding to the technkiues in this 
article as well as those in the First two parts, in case you missed 
them the first time around. 

SiTiiPED Tabu Rows 

If you want your table display to look like one of Apple’s 
applications like iTunes, or ju.st to make your list more 
readable, you may want to consider alternating row 
background colors. Al first glance, it seems that the best way 
to accomplish this is to intercept the tableView: willDispiayCell: 
forTableColumn: row: delegate message and set the cell’s 
background color depending on whether the row is even or 
odd. Unfonunately, this only stripes the cells with data, rather 


than the entire tal3le; it also works only for text cells, not button 
or image cells. 

A better approach is to create a subclass of NSTableView 
and override highrightSelectionInClipRect: (listing 1) to draw the 
stripes. Tliis method draws stripes in the background by 
alternating between the “even’’ color of light blue and the '\3dd” 
color of white. 


Saw 

Sign 

Name 

□ 


Julie 

V 


Sandra 

□ 

HP 

Reginald 

□ 


Hakim 

V 


Rich 

□ 


Sophia 

□ 


George 

□ 

■ : 

Darnell 

□ 


Roxanne 

V' 


Korvax 


Figitrt' L Alternating Roivs and Verlicai Grids 

listing 1: StripcdTableView.m 

h ighlij^htSdectionlnCIi pRect: 

DispUy the badqjroLind lor t!ie ial>Jc in the given dipping reLtanglc. 

- (vcidlhighlightSelectionlnClipRectI(NSRect)clipRect 

f 

N SCo lor * even Colo r // enTpiricaJly detemiint^d color, matches iTunes etc. 

^ [NSGolor colorWithCalibratedRed:0.929 


Dan Wocxl, the son of an organic cropduster pilot and a neurosuigeon, grew' up in Amish Pennsylvania, hack in the roaring twenties. As a child, he 
watched Lost in Space and Pow'erpuff Girls on TV. After graduating with a degree in Chocolatology from tJie University of Hershey, Dan joined the 
Peace Corps, teaching American Sign Language to underprivileged dolphins. He is cunently a road crew foreman for the California Department of 
Transportation (CalTrans), and has written a successful application in Cocoa called Watson. Dan thanLs Chuck Pisula at Apple for his technical help 
with this series, and acknowledges online code fragments from John C. Randolph. Stephane Sudre, Ondra Cada, Vince DeMarco, Harry Emmanuel, 
and others. You can reach him at dwood@kareha.com. 


64 


TABtE Techniqltes Tal’ght Tastefltly (part 3 ) 


MacTech • Nowmber 2002 














Visual 
Get up 


QuickStart Guides 
and running quickly! 


Save 20% 

off these titles at 


BORDERS* 


*Sale begins 
November 3 , 2002 
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HTML for the World Wide 
Web, Fifth Edition, with 
XHTML and CSS: Visual 
QukkStart Guide 

Elizabeth Castro 
0-321-13007-3 -$21.99 


The Web is changing how it does business and so 
should you! If youVe still coding like it was 1999, you 
need to update your HTML skills with Elizabeth 
Castro's HTML for the World Wide Web, Fifth Edition, 
with XHTML and CSS: Visual QuickStart Guide. This 
latest edition of the original book on HTML will have 
you creating complex, dynamic sites that look good 
across all browsers and platforms—including hand¬ 
held devices and cell phones—in no time! 



PHOIOSHOP 


JiaA jTurzv (hr 
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PhQtOshop 7 for Window/s 
and Macintosh: Visual 
QuickStart Guide 
Elaine Wsinmann and 
Peter Lourekas 
0-'201-BB284-1 * $24.99 



RNiKiirnios 



Final Cut Pro 3 for 
Macintosh: Visual 
QuickPro Guide 
Lisa Bren ne is 
0-321-11533-Xt $29.99 


MMOSX 
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Mac OSX 10.2: Visual 
QuickStart Guide 
Marla Lartger 
0-321-1S801-6- $21.99 


Macromedia Flash MX tor 
Windows and Macintosh: 
Visual QuickStart Guide 
Katherine Ulrich 
0 201-79481-0- $24,99 




Macromedia Dreamweaver MX 
for Windows and Macintosh: 
Visual QuickStart Guide 

J. Tarin Towers 
0^201-84445-t - $24.99 



SQL: Visual QuickStart 
Guide 
Chris Fehtly 
0-32M1S03-0* $21.99 
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JavaScript for the World 
Wide Web, 4th Edition: 
Visual QuickStart Guide 
Tom Negrfno and 
Dori Smith 

0-201 73517-2 -519.99 
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Macromedia Flash MX Advanced 
for Windows and Macintosh: 
Visual QuickPro Guide 
Russell Chun 
0-201-75846-6 ■ $29-99 


*Sale Dates: 1V3 ^2002-1/31/2003. 
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green »0.953 bine lO. 996 alphaU.Ol: 

NSCalor ^oddGolor = [HSColni: whiteColor]; 

float rowHeight 

= [self rowfleight] + [self intercellSpacitigllheight; 
NSRect vlsibleRect “ [self visibleRect ]i 
NSRect highlightRect; 

hlghllghtRect.origin = HSMakePoint( 

NSMinK(visibleRect3. 

(int){NSMiny(clipRect)/rowHeight]•rowHeight ); 
highlightRect,size = NSMakeSize[ 

NSWidth(visihleRect)* 

rowHeight - [self intercellSpacing].height )i 

while (NSMinY[highlightRect) < MSHaxYCcllpRect)) 

( 

NSRect clippedKighlightRect 

= NSIntersectionRect(highlightRect. cllpRect): 
int row = (intj 

((NSHinY[highlightRect)+rowReight/2.0)/rowEeight); 
biSColor *rowColor 

= (0 = row % 2} ? evenColor : oddColor; 

[rowColor set ]i 

NSRectFlll(clippedHighlightRect): 
highllghtRect.origin.y += rowEeight; 

[ 

[super hlghlightSelectionlnClipRect: clipRect]; 


To mimic the iTunes IcKik even further, you may want to 
draw a grid, but only the vertiatl fines between columns, not the 
horizontal lines betw^een rows. So w^e override drawGridlnClipRect: 
and provide our own implementation ( Listing 2) tliat drawls light 
gray vertiatl lines. 


Listing 2 : StripedTafoleView.m 


drawGridlnCIipRect; 

Ditiw the grid, hut only' the vertical lines 

- [void] drawGridlnCIipRect: (tlSRect) rect 

( 

NSRange coluTWiRange = [self columnsInRect:recti ; 
int i: 

[[NSColor lighterayColor] set]; 

for ( 1 = coliLEumRange.loretInn ; 

i i NSMaxRangeCcolumnRange) ; 

1 ++ ) 
t 

NSRect colRect = [self rectOfColumn;i]; 
int rightEdge 

= (int) 0.5 + ColRect.origin.x t coLRect,size.width: 
iNSBezierPath strokeLineFromPoint; 

KSMakePointf-0,5+rightEdge^ -0,5+ rect .origin,y) 
toPolnt: 

NSMakePoint(-0.S+rightEdge. -0.5+rect.origin.y + 
rect.size.helght}]: 

I 

1 

Vbila! Striped tables, as in Figure 1. Now you can write the 
next iAppI 


Merging m\BiE cells together 
So far, all of the subclassing of NSTableView that weVe 
done in this series are pretty straightforward, and modify the 
default behavior only subtly . But what happens w^hen the class 
is radically subclassed? Well, one example of this is Cocoa's 
own NSOutlineView, a subclass that barely resembles its parent 
in the way that it structures and presents its contents. In this 


segment, well try something a bit less ambitious, but 
significant nevertheless. 

The challenge is this: to have a table view in which certain 
columns are merged together with their neighboring columns. 
An example application would be a daily schedule in which 
appointments take a variable amount of time. You want the 
cells to span across multiple columns, not constrained to 
individual columns. (Readers familiar with Hl'ML can equate 
this to the “colspan" attribute of a <TD> tag.) 

Tlfere are two sides to making this work. One is to modify 
die controller code that provides the data for tlie table to 
display; die other Ls to implement die view (the NSTableView 
subclass, which w^e aill MergedColumnTableView) to display 
die data provided by the controller. 

For the controller, we invent a new meihcxl for an informal 
protcx:oi for your controller to define; 

[int)tableView:(NSTableView *JtableVlew 
spanF<}rTableColunin: (NSTableColutim *) table Column 
row;(int)row; 

Our implementation should return 1 if the cell is one 
column wide (the usual case); 0 if no data is to l>e shown in the 
column (generally the case if it is to the right of a multiple-cell- 
spanning table), and a numter greater than 1 if the cell is to span 
more than one column to the right. Because we pass in a pointer 
to the table view, diis method can lie used even if diere is more 
than one table that your controller controls; because we pass in 
a low' numlier, each row can liave difler in its presentation. 

llie TableTester application Licconipaiiying diis article reads 
in a sample '‘class schedule"* from a property list file, and 
implements die standard NSTableView data source methods of 
numberOfRowslnTabteView: and 

lableView:obj©ctValueForTableColuinn:row: as w^ell as the spanning 
meihcxJ for this protneoL We w'on'i be examining the controller 
implementation in-depth here, since its very dependent on the 
data structure. Unlike a typical table display, w^here an array of 
dictionaries will usually suffice, the data to display is more 
complex. So if you need to display data that spans multiple 
columns, you can take advantage of MergedColumnTableView, 
but you are on your own for implementing the controller (This 
is yet another reason w^hy it's gocxl to partition the view\ the 
controller, and the model!) 

How^ the MergedColumnTableView^ subclassing w^orks, on 
the other hand, is significant, because it may help reveal 
techniques that you can use for other table subclassing needs. 
We override three metiiods of NSTableView: 
frameOfCellAtColumn: row:, to override the rectangle for a given 
cell to take the column spanning into account; draw Row: 
clipRect:, to manage the drawing of all the columns in a row; 
and drawGridlnClipReGt:, to draw the table grid lines In such a 
way tliat merged cells liave no grid line between diem. (Each 
of diose mediods prtjvides a special behavior if the data source 
implements our additional metliod; if not, the superclass 
provides die dehmll behavior.) 

The mt)st important override Ls frameOfCellAtColumn:row:. (See 
listing 3 ) Thus is the methcxl that calculates die rectangle 
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associated with a given cell for each colmnn and row. Since our 
goai Ls to make ilie cells wider tlian tliey would nonnally te, this is 
the [agicA\ place to modify die default table lieliavior. All we have 
to do is find C3UL tlie nLtmber of columns that the given cell should 
span, and return an appropriate rectangle. If the column span is 
7i^rc>, we return an empty recuingie, NSZeroRect. If die column span 
is one, we lei tlie superclass calculate the rectangle, sincx^ nodilng is 
different about a cell widi a column span ol' one. If die column span 
is greater tlian one, we collect up all the rectangles of die current 
cell and the cells to the right by invoking die suiXfrdass’s method, 
meiging the rectangles together into one bigger rectangle. 

Listing 3: MergedColumnTableView*in 


Rcmm ihc tccLinfilc fi)r the given ceU. litis may l>ehavc like its superclass, or it may 
retiim an enipty^ rectangle or a wider reaangk if the table's column span is not one. 

- (NSRect)fraineOfCellAtCQlunin: (int)colmitn row:(int)raw 
I 

int colspan: 
if (![[self dataSource] 
res pond sToSelectoi:: 

^selector (tableViewt spanForTableColuam i row:) ]) 

[ 

return [super frameOfCellAtColunm:column row:row] : 

colspan ^ [[self dataSource] 
tableVlev:sGlf 
spanFarTableColuJim: 

[[self tableColumnsJ obJectAtIndex;column] 
row:row]: 

If (0 = Qolspan) 

( 

return NSZeroRect; 

] 

if (1 = colspan} 

I 

return [super f rameOf Cell AtColumn; column row: row]: 

1 

else // 2 or more, it’s responsibilitv of data source to pnnide reasonable number 
( 

NSReet merged 

= [ sup e r f r ameO f C e 1 lAt C o lumn: c o 1 umrv r ow: r ow J; 

// siart out wiUi tliis one 
int i: 

for (1 = 1; i < colspan: 1++ )//stan from next one 
I 

NSReet next 

" [super frameOfCellAtColurnn:column+i row; row]: 
merged = NSTJnionRect[merged,next) ; 

I 

return merged: 



Tlie above override covers most of the needed functionali!y\ 
but a couple of subtle items remain. When horizontal scrollbars 
are used in the talile, you will find that some table cells don’t get 
drawn on die left edge of the table. This is because the standard 
NSTableView draws only the cells tliat are currently visible 
within the NSScrollView, and it dex^sn’t realize that a cell 
spanning multiple columns needs to be drawn even if it starts to 
the left of the visible rectangle. (See Figure 2.) So we override 
drawRow: clipRect: (listing 4) to Icxik at the leftmost column, 
and if the cell there has a column span of zero, it needs to "back 
up” to the left and find the cell that spans multiple columns. 
Once it finds that celf it expands the clipping rectangle so that 
the wide cell will be drawn and thus appear in the visible region. 
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column span of two 

colspan=1 

cx)lumn span of two 


i______________ 



dipping rectangle 


We extend the clipping rectangle so this cell is drawn 



Figure 4 Grid line^ match the column 


Figure 2. Missing Cohmm 


Listing 4: MergedColumnTableView.m 


tjptAhL-:idString:mTabJeVi<fw: 

Actually select the appmphate ruw based apjn the siring that has been typed, 

- (void) dravRow: (int) IriRow ciipRect: (NSRect) inClipRect 

[ 

NSReet newCllpRect = inClipRect; 
if ([[self dataSDurce] 
respondfiToSelector: 

@selector(tableView:spanForTableColtnBnt row:)]) 

I 

int colspati = 0: 
int firfitCol 

- [self coluiniisIiLRect:InClipRect]. location: 

// OCJCS the URS'r otic of these have a zerocolspan? 11 so, extend ttingc 
while (0 = colspan) 

I 

colspan = [[self dataSource] 
tabieVlewtself 

spanForTableColuran:[[self tableColumns] 
obj ECtAtInd ax:f1rstCol] 
rowiinRow]; 
if [0 = colspan) 
t 

firstCol'': 

newCllpRect = NSUnlonRect(newClipRect, 

[self frameOfCellAtColumn:firstCol row:lnRow]): 

1 

1 

I 

[super drawRowiinRow clipRect:newClipRect]: 

] 
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Figure 3; The grid lines don V look righc 


With the above override, all of tiie cells will display, hut 
what if you want to display a grid to make the cell sizes clearer? 
If we use die standard grid, the table wt:>uld look like Figure 3, 
with vertical lines cutting across our wide cells. So w^e 
implement a new grid that takes the column spans into account, 
drawing vertical lines only before or after cells. If you have a 
"sparse" display (such as the example class schedule here), it 
looks even better if you give the table a distinguishing 
background color. The final result is in Figure 4. 


The drawGridInClipRect: override (listing 5) determines all 
of the rows and columns diat will need to be drawn for the 
given clipping rectangle. It then loops first tlirough each row, 
drawing the horizontal lines using NSBezierPath methods, then 
loops through each town’s columns to draw the vertical lines. 
Similarly to the frameOfCellAtColumn.row: override, it builds up 
the rectangle for a cell .spanning multiple columns by growing a 
rectangle using the NSUnionRect operation. 

Listing 5: MergedColumnTableView.m 


(y pc Aht-udStilng: inTabte Vie w: 

Attimlly sek-Li die :ippropriate niw b;i,sfd upK>n the Ntrin^ that has been typt^tl 

- (void IdtavGr id InClipRect: (fJSRect] rect 

t 

if (I [[self dataSnutce] reEpondsToSelectai:' 

©sElEctor (TableViewi spanForTablcColumntrowi) ]) 

I 

[auper drawGrldlnClipRect:rect]: 

] 

else 

I 

HSRange rovRange ^ [self rowsInRect:rect] ; 

NSRange columisRange ” [aelf colLaimsInRECt : rect] : 
int row; 

//Adjust column range,always go from 'Jtero. so we ean gather colvimns even to 
// the left of what wc are suppo-scd to draw. 

coIurnnKangs = NSMakeRange(0»NSMaxRange(colmnnRange)): 

[[NSCoiot grayColor] set]: 

for t row = rowRangEtlocation ; 
row < NSMaxRange(rowRange) : 
row++ ) 

( 

int col = calumnRange.location: 
int oidLeftEdge 

= 0.5 + [self rectOfColuninrcol] *origin.x| 

NSRact rowRect - [self rectOfRowirow] r 
// here, frame not the top and not the left, but the btjrtom 
[ffSBeziErPath stroRaLlneFromPoint: 

NSMakePoint (rowRect.origin. x. 

- 0, 5+rowRect.origin .y+towRect v size .height ) 
toPoint: 

NSMakEPointCrowRect.origin.X + rowRect.size.width, 
-0.5+rowReet .origin,y^-rowRect.size .height)]; 

vh-ilE ( col < NSMaxRangetcoluninHaiigEj ) 

( 

int colspan = [[aElf dataSource] tableViev:seif 
apatiForTableColumn: [[self tableColmnna] 
obJectAtlndex:col] row:row]: 

NSReex gridRect “ HSZeroRect: 
if (Q “= colspan) 
i 

c 0 1 -H-: // DO grid here. move along 

I 

else // P^ow gather up the next <eoLsp:iii> rectangles 

I 

int i, rightEdge. leftEdge: 

for ( i = 0 : i < colspan ; i++ ) 
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REAL Software and MacTech present the REALbasic Showcase to 
highliglit some of the fantastic solutions created by REALbasic users 
worldwide.Tlie showcase illustrates the wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific. All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www.realbasic.com>. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 
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Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
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Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic. 

Supported Algorithms: 

• Encryption: 

“ e-CryptIt 

- BlowFish (448 bit) 

-AES (RIjndael) (256 bit) 

• Encoding: 

- e-Cryptlt Flexible 

- Base 64 

- BinHex 

- MacBinary III 

- AppleSingle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams (.gz) 

• Hashing and Checksums: 

-CRC32/Adter32 

- MD5 / HMAC_MD5 
-SHA/SHA1 /HVIAC^SHAI 


other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 


Format 


Font 
“ Si2e 



Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 


Einhugur Software 

sales@elnhugur.com 

www.einhugur.com 



TelnetLauncher 

Bookmark and Launch your 
Telnet and SSH sessions 


piPop 

Pop-up Hierarchical 
File Navigation and Launcher 




§lk: SimpleKeys 



Set your Function Keys 
to type stuff for you! 


piDog Software 

http://www.pidog.com/ 


whistle Blower 

Enterprise server monitor and restart utility 
whistiebloweresentmanecom 

Connect to and validate the response from web servers^ 
cgi scripts and over 23 other types of servers. 

Send email pages and perform unotfended restarts via 
MasterSwitch or PowerKey. 

Shifts moke sure that the person on call wlien the server 
goes down is the one who gets the page. 

68k, PPC and Corfcon 

Web based odm/n/sfrof/on lets you check on and restart 
your servers from anywhere. 

Customize your response to an outage with Apple Script. 

email us at whistleblower@sentman.com 
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* build both Macintosh and Windows screensavers 
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Macromedia Flash S.O, MPEG, Onepak, MP3, Midi, AVI, DV Video... 
or, now with version 3.0, build your own basic Slide Shows I 

• include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

• Screensavers install without DLLs, extensions, or restarts 


Simple m 
WYSIWYG 
editor | 
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interactive Flash I 
and QuickTime 
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cross-platform 
user Interface 


try before you buy 
fully functional 
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creating screensavers 
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NSRect thisRect = MSIntersectiotiRecr( 

[self rectOfColumn:col+i] ^ 

[self rectDfRow: ro-w] ) : 
gridRect = HSUnlonRect(gridRect.thisRect): 

\ 

Qol += colspan; 

// left etlge. Onlj^ draw If this left edge isn't one we just drew. 
leftEdge “ (itit) 0.5 + gridRect .origin, x: 
if (leftEdge [” oldLeftEdge) 

( 

[IJSBe^lerPath strokeLineFromPoint: 

NBMakePoint( 

-0.5+leftEdge. -0>5+aridRect.origin.y) 
toPoint 2 

NSMakePoint(^ 0.5+leftEdge. 

-0.5+grldRect.origin.y 
+ gridRect.size.height)1t 
J 

// riglu edge 

rightEdge = (int) 0.5 + gridRect.origin.x 
i gridRect.size.width: 

[NSBezlerPath strokeLinefroniPoint; 

NSMakePoint[’0.5+rigbtEdge, 

-0.5+gridRect.origin.y) 
toPolnt: 

NSMakePolnt(■0.5+rightEdge, 

-0.5+gridRect.origin.y 
+ gridRect.size.height)]: 

□ IdLeftEdge " rightEdge ; // save edge lor next [wss ihnnigh. 
I 

1 


'['hat's all there is to it. OK, may tie ihai one wasn't so easy. 
If you are going to be heavily siibelassing NSl'ableView, realize 
that it is going to take a lot of trial anti error, research, and help 
from other smart people to get it to work just right. Stibelas.sing 
any object for which you don’t have ilie source code is never 
easy, l>ecause you don’t know al! of the .subtle interactions 
among the metUtxls that you might be able to see if it was your 
code. Still, it is possible to modify NSTableView's default 
behavior by modifying ju.st a few methods. 

Ci tSTOM Cell Cla.s.ses 

That last one was a bit deep, .so lef.s lake a breather and tiy 
.something a little ea,sieL How^ do you make a “relevance" indicator, 
like you see when you search for items in liie Finder'* (See Figure 
5. ) As of Mac OS X 10.2, there is now a standard w idget you need 
to use, but no such cla,s.s has lieen provided in Cocoa fov us to use. 
.Since a Table displays cells, we need to make our ow^n ciisroni 
sijbcla.s.s of RSCell. We’ll call the class “RankCell" tecau.se it's easier 
to spell than ’RelevanceCell.'' (See Listing 6J 


Rank 



Figure 5 Relevance cells in a table 


Listing 6: RankCeil.m 

// dechre a iftatic variable that will hwld the pattern, 
static NEImage *sRankPatternlmage = nil: 


iiiiiializc 

When ihe class is initialized, load in the striped partem from an image in the project. 


+ (void) initialize 
I 

sRankPatternlinage 

= [[NSlmage imageNamed;@"atrlpe’*] catain]: 

[ 


floarValue 

Return the value {)f the cell (a number from 0.0 to LO) as a lloating point number. 

'Jilt method verifies that live celPs asstjciated object value is indeed an objeei titat e^an 
return a float. (Both NSNumber and NSString respond to QoatValuef) 

- (float) floatValue 

I 

float result ^0.0: 

id objectValue = [self objectValue]: 

if [ [objectValue respondsToSelector: 

^seiector(floatValue)]) 

I 

result = [(NSNumber •}objectValue floatValuej ; 

I 

return result: 

I 


setFloatValite: 

Set the vidue of the cell to a niimber between 0,0 and 1,0, 

- (void) setFloaiValue:(float)inValue 
i 

float value “ inValue: 

If (value ) 1.0) value = 1.0; 
if [value < 0.0) value =0.0: 

[self setObjectValue: [NSNumber nLkmberWithFlQat;value]] : 


tiraw I n teriuTWiih Frame: i n V ie w: 

Draw the cell. I he cell will he smaller if its contrtilSize is NSSniLiUControlSize. 

(void) drawInteciorWithFrame: (HSEect)inFrarae 
inView: (NSView*)InView: 

[ 

float drawWldth: 

NSRect fillEraine, eraaeFrame: 

// C’unstniin the frame's height 
float yinset 

= (NSSmallControlSize ^ [self controlSizeJ) 

? 4,0 : 3,0: 

NSRect newFrame “ NSInsetRect(inFrame. 3-0. yin&et) ; 

// Cailculalc widili uf fitletl part 
drawWidth 

= floor([self floatValue] * newFrame,size,width): 
if (drawWidth < 1) 

I 

drawWidth = 1: // al least 1 pixel wide, so we see something! 


NSDivideRect (newFrame, SfillFraine , ^eraseFraine. 
drawWidth. NSMnXEdge); 

[[NSColor colorWithPatternlmage:sRankPatternlmage] set]: 
[NSBezierPath fillRect'.flllFrame] : 


All wc need to do is to set our table to use our RankCell 
class. As LLSual, a good place to do this is in an awakeFromNib 
method. (See Listing 7.) Then you have your data source's 
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tableView: objectValueForColumn: row: method return an 
NSNumher between 0.0 and LO, That ’5 it! 

Listing 7: CeJJDelegate.nni 


awikcFnimNib 

Crrjite a RiinkCelJ and stt it as a column's cdL 

- (void)awakeFromNib 

t 

RankCEll •rank.Gsll 

= [[[RankCell alloc] init] autorelease]: 

NSTableColimm ' raiikColumi] 

= [oTable tableColimirLWithIdentifier:@"rank"]: 

[rankCell setControISizeilJSSmallCDatrolSlze]: 

[rankColuMi setDataCell:rankCell] : 


ANIMAITD SOffriNG 

If you've .seen iChat, you have probably noticed the slick 
animation when people on your Buddy List change status. Die 
table elements animate as they move around. Very slick, but 
how did they do it’ It probably involved subclassing 
NSTableView. Inspired by some Apple sample code called 
“AnimatedSlider” that animates the transition between values of 
an NSSlider (much like the preset equali2er settings in iTunes), 
IVe determined out how' to do this, and 1 present the technique 
here. (If s hard to show^ animations in print, but Figure 6 should 
give you an idea of what it looks like.) 
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Figure 6: Animaied SoTiing: Before, During, and After 


Tlie trick is to override tlie NSTableView method rectOfRow: 
and invoke it multiple times over a second or so, to move the 
rows from their old positions to dieir new ones. Unlike die 
“AnimatedSlider" example, which managed to put aU the 
animation functionality into a category method on NSSlider, this 
is a little bit more complex, so we need the controller invcilved 
as well. So to keep the view separated as much as possible from 
the controller, die NSTableView subclass—^.AnimatedTableView^— 
lets its delegate (or its data source, if you desire) Uike care of the 
logic associated with the animation, (See Listing SJ 

Listing 8; AniniatedTableView*in 


rtciOfRow: 

Override NSTsibJeView's mediod that calculates the rectangle of a given row. Let the 


delegate determine w liat the recyingle for a given row is. if that delegate responds to 
the selector to do so. if animation b gcjing cm, it will pnibabiy rcnirn a value other 
than die default. 

- (NSRect)rectOfRow:(int)towlndex 

I 

NSRect theOefaultRect = [super rectOfRow:rowindex]: 
if (llself delegate] respondsToSelector: 

^selector[tableView:rectOfRow:defaultRect :]]) 

I 

return [[self delegate] 

tableView:self rectOfRow:rowlndex 
defaulrRect:theDefaultRect]; 


else 

( 

return theDefaultRect: 

I 


unanimatedRectOfRow: 

Ecmm the defeult NSTableView's version of the rectangle for a given row; this method 
b provided so we can detcnnine the rectangle as if animation weren 'l happening. 

- (NSRect)unanimatedRectOfRow:[int]rowlndex 
I 

return [super rectOfRow:rowlndex]: 

} 


rowslnllcct: 

Override NSTibleView's method that determines what rows are visible for a given 
K*ctang]e. Let the delegate determine what the range of rows is for a given recuiigle. 
if that delegate a'sponds to the selector to do so. If animation is going on, it will 
probably return a value other thati the default. 

' {ffSRange) rovsInRect: (NSRect) inRect 
I 

NSRange tbeDefaultRange = [super rowsItiRect:inRect]: 
if ([[self delegate] respondsToSelector: 

^selector(tableView:rowsInRect rdefaultRange:}]) 

f 

return [[self delegate] 

tableView:self rowsInRect:InRect 
defaultRange:theDefaultRange] : 

) 

else 

I 

return theDefaultRange: 

I 

] 


In order to animate the rows m a table, we need to keep 
track of both die original positions and the new positions of 
each row in the tabic! One way to do this is to build a new 
array of index values so w^e can lookup the original array 
position for any row in the sorted array. For example, if an 
array containing E, G, B, D, F is sorted into B, D, E, F, G, then 
we could build an array containing 2, 3, 0, 4, L Element 0 of 
die new array, B, used to be at position 2 in the old array; 
Element 1, D, used to be at position 3, and so forth. And what 
better way to implement diis using a category mediod on 
NS Array! (See listing 90 

Listing 9: SortingDelegate.m 

©interface NSArray (flndPositions) 

(KSArray 

fIndPoBltioELs InUusortedAr ray: (I^SArray *) fromArray i 

©end 

©jjffiplenientatioii NSArray ffindPusitions) 

findl^idonsInLinsuiicdAnay: 

Build an array of NSNumhers. representing the position each item of on array used to 
be before it was sorted. 
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[NSArray *) 

findPosltlonsInUtisortedArrayi [NSArray *) framArray 

f 

NSMutableArray "result 

= [MSMutableArray arrayWlthCapacityt[self coimt]]; 

NS Enumerator *tlieEnum = [self objectEnumerator]: 
id object; 

while (nil (object ^ [theEnuia nextObject]) ] 

( 

int indexInOld “ [fromArray indexOfObJect;objectJ : 
[reault addObject:[NSNiimbet numberWithlnt:IndexInOld]J; 

] 

return result; 

] 

@end 


Now it’s time for the actual animation, defined in 
SortingDelegate,rii. (Note that this class coatains three relevant 
instance variables; mTimer, a reference to the NSTimer used for 
sorting; m Old Positions Array, the lookup array descritied above; 
and mAnimationPosition, a floating point value representing how^ 
Far along in the animation we are,) Let’s dive right into Listing 
10 for the methods we need. 

Listing 10: SortingDelegate.m 

//The "frame rate" fur animaUnj; the titbit sort, 
const float kFtameRatE = Ll)/ 30 : 

// Ihimtion of the animation, pnibahly shouldn't tn: more than a second, 
const float kAuiniatlonTiinG = 0 . 75 ; 


st‘tOldt\>sitions Array: 

Set tlie array that holds die old positions of die Items before diey were sorted. 

- (void] setOldPositionsArray;(NSArray ")inNewValue 
I 

[inNewValua retain]; 

[mOldPositionsArray release]: 
mOldPositionsArray = inNewValue: 


stopAnlmadn^ 

Remove any ajimiatmg NS'llmer Also clears niAnimationl^Jsition to intlkate that we 
are no longer aoimating. 

- (void) StopAnimating 
I 

[mTimdr Invalidate]; 
mTimer = nil: 
mArdmationPositlon = 0; 


setTimer: 

Set ihe animation timer, replacing any existing one. 

- (void) setTimer:(NSTimer *)ioNewValne 
[ 

[inNewValue retain]: 

[laTijiier release]: 

[self stopAniaiating] : 
raTimer = inNewValue; 


table View: n w si n Rect: dcfaultRangc; 
Invoked by AnimatcilTableVlew, [f we re currenUy aniniaiing, we just return the entire 
range of aJl rows, so that all rows get drawn no matter where they are. (Tliey w^ill stUl 
be clipped properly but if we tiont override this, then some rows may nor \w drawn,) 
Tbea' are probably ways to make this more ellicieni.ealeulaiing which rxjws need lo 
be displayed, but as long as our table isn’t too big, this should lie fine. 

- (NSRange}tableView:{AnimatedTableView *JinTableView 
rowsInRect;(NSRect)inRect 
dEfaultRange: (NSRangE) itiDef aultRangc 

I 

if (mAnimationPosition > 0} //am we eurrcntly animaiing? 


I 

return NSMakeRange (0, [oData count]) : // just reium ail rows 

] 

else 

I 

return InDefaultRange: 

} 

I 


tableView:reet()fHt)w; delaultRect: 
Invoked by AnimaiecTl ableView. Returns a rectangle for tlie given row in the table. If 
we are animating, we calculate a rectangle to be be some percentage of the 
between the row's old rectangle and its new rectangle. 


(NSRect)tableView:(AnlmatedTableView •)inTableVie¥ 
rectOfRov; (int)liaRawIndex 
def anltRact: (NSRcet) inDefaultRect 

( 

if (mAnimationPositlQn > 0) //areweeuntmlyanimating? 

{ 

// Get the rectangles of where the row^ originally was, and where it will end up. 
int oldPosition “ UmOidFositionsArray 
objectAtlndex:inRowIndex] intValue]; 

NSRect oldR 

= linTflbleView unaniiaatedRactOfRow;oldPosition] ; 

NSRect nevB 

“ [inTableView unatilmiatedRGCtOfRovj; inRowIndExJ : 

//1 will be our fractuin between 0 and 1 of how far along die row .should be. 
float t " inAnimatlonPosltlan: // lineiu- position based on time 

// Calailate a rectangle between the original and the fmal rectangles. 

NSRect newRoct “ NSHakeRect( 

NSHinXfoldR) + (i " (NSNinX(newR) - NSHinX(oldR))), 
NSMinY[oldl) + {t " (NEMinY[newR) - NSMinY{oldR))). 
NSWldthCnowR), NSHelght(newR) }; 
return nawRect; 

I 

else 

( 

return inDe fault Rect: // not animaiing, just return tlie standard value. 


aniraateStep; 

Invoked by ihe NSTimer multiple limes to handle the animation. Cajculaic the 
position we are b:ised on the currcni tlnie^smd then either force a display of the table, 
or stop the animatitin. 

- (void) animateStep: (NSTimer *)±nTiiaer 

[ 

NEDate "start “ (inTimer userlnfo]: 

NSTimelnterval elapaed 

fabs [ [etart timcIntervalSinceNow]) t 
itiAniiiiationPosltion ^ WIN(1.0 . elapsed / kAnimationTime); 

// Done yet? Allow a bit of "servo jitter" to allow for floating point messiness 
if (fabs(mAnimationPosition - 1.0) 0,01) 

[self BtopAnimating]; 

[oTable dlEplayl: // force a display of the table in its normai state 

J 

el$E 

I 

[ oTa ble display!: // force a display of the table in its new state. 

I 


tableVlew: animaicSonFronulrray: loArray: 
Initiate an animated sort. We pass in tlie old !u-ray belbre the sort, and the new sorted 
airay. It kicks ofT a timer t(t start the animation with the current date/tJme pa.ssed in 
a.s user info so it can keep traek of how for along the animation it is. 


(void)tablaView:[NSTableView ")inTableView 
animateSQrtFracQArray: (NSArray *) fromArray 
toArray: (NSArray ")tC3Array 

I 

NSTimer •timer: 

NSRange visibleRows; 
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[self St 5 }pAnimating]; // Stop any existing sort animation 

[self setOldPositionsArray: 

[toArray findPositionsInUnsortedArray:fromArray]]: 

timer ^ 

[NSTimer scheduLedTimerWittiTljnelnterval: kErameRate 
target i self 

selector :@selectcir (afilmateStep:) 

user Info: [HSDate date] // store the starring date as user info 

repeats:YES] : 

[self setTimer: t imer]: // store tJic timer so we can stop it tvhcn done. 


SiirtDam 

Acniaily sort the data This Ls an extension of the sortData method described in part 2 
of this series. For this sample. If the applieadon delegate method ammateSores tetums 
YES^ tJien kick off die sovL Otherwise, sort withemt animatiem. In either case, the 
table selection Is preserved across tlie sort so diat any rows selected before the sort 
will be properly selectetl in their new positions after the sort. 

- (void) sortData 

f 

SortContext ctst^l inSortingKey, mSortDescending I; 

NSSet ^oldSelGQtion 

= [seif saveSelectionFromTabla:oTable] t 
if ([[NEApp delegate] animateSorts]) 

I 

NSArray *originalOrderArray ^ [oData copy]: 

[oData aortUsingFunction:ORDER_BY_CONTEXT 
context: fitctxt]; 

[self restoreSelectlonroldSelection toTable:oTablc 
refresh:N 0 ]: 

[self tableView:oTable 
aniraateSo rtFromAr ray:originalOrderAr ray 
toArray:oData]; 

//When done, the data shotdd be displayed correctly. 

] 


else 

( 

[oData sortUsingFunction:ORDER_BY_CONTEXT 
context:&ctxtj: 

[oTable reloadData]: 

[self restoreSelectioti:oldSelection toTable:oTable 
refresh:YESj; 

I 

I 

That's all that’s needed for a basic animated son. You may 
find that you need to implement your own animation code 
differently to deal w itii your application's specific needs, bur this 
should give you the basic idea. You are w'amed: This is nor 
going to work very w’ell on very large tables, since the position 
of every rew in tlie table is being calculated repeatedly, 
regardless of whether it is visible or not. But for reasonable 
sizes, the animation can add a nice extra dimension to your 
interface. 

There are a couple of visual improvements diat can be made 
to the animation, however. The iirst improvement, demonstrated 
in tlie AnimatedSIider example, is making the movement seem 
more namral by letting tlie movement accelerate rather than 
abruptly clianging from standing still to moving full-speed- 
Currently, the Y value (vertical position) changes linearly with 
respect to time, as depicted mathematically in Figure 7. It is 
possible to adjust the position by inserting a sine function into 
die c'alculations to ease the transidon. listing 11 shows the 
function to convert a value bem^een 0.0 and TO inlo iLs eased 
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equivalent, depicted in Figure 8. All we need to do is insert t ^ 
ease Function (t); into tableView: rectOfRow: defaultRect:. 




Listing 11: SortingDclegate.m 


eyscFunction 

This ftinction implements n siniiwjitki estse-inyeasie-cju!: Ibri = 0 to LO. T is sciiled to 
represetit the interval of one full period of the sine function, and transposed to lie 
ahtn-c the X axis. 

float easeFunction{float t) 

return tsin(Ct * H_PI) - M_P1_2) + KO ) / 2.0: 

1 


The other visual improvement that can be made Ls only 
apparent when you animate the reversal of a sort, changing from 
ascending to descending sort order, or vice-versa. Since the first 
items in the table exchange thenTseives symmertically with the 
last items, tliey aU end up bunching together in the center of the 
table halfway through the process. (See Figure 9 ) it doesn't 
look as cool as it could. How can we make the movement a 
little bit less symmetrical so tliat everydiing doesn't crowd the 
middle of tlie table? 



Figure 9: Rei^emng sort order bunches up in the middle. 


If we could vary the “speed" ot each row^ so that the rows 
at the top of the table move at a different rate than the rows at 
the bottom of the table, this would prevent the traffic jam in the 
center of the table. One way to do tliis is to use a “curve” 
function to move row^s, with a different parameter used for each 
row. A reasonable function is shown in Figure 9, M we need 
to do is vaiy the powxT (n). Rows at one end of the table use 
a value slightly less than one; the middle row uses a power of 
one (a straight line); Rows at the other end of the table use a 
value slightly greater than one. We get a different curve for each 
rr>w^ and each row' moves ai a different rate. 



The effect of this is very nice; it looks as if die rows are 
doing a “back flip” as they sw'ap their positions. Figure 11 
might give you a sense of how it looks, but it’s more fun to see 
it in the program itself. 
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Figure 11: Adding a \ufve'' makes a reversal look nicer 


If you happen to be viewing only a piece of a table—say, 
the top half or the bottom half—and the rest is scrolled out of 
view, It can look pretty strange for the rows to move out of view 
and tlten move back into view a moment later. So wc can 
perform an adjustment to the swapping behavior so that the 
curve is "centered” on the half of the table that you are looking 
at. So if you are viewing the top half of a table, the curve will 
be flipped compared to viewing the bottom half of a table. 

Listing 12 shows the function you need to convert the '‘t" 
value into its curved counterpart. 

Listing 12; SortingI>elegate*m 

// "curvy"' the inovement Hhould be, t).2 or (y.3 L'j :i nice value: O.S Ls funky f 
const float kCurve “ 0,3: 

curveFuncrion 

This hinetion is used to de<enrer t [from 0 to l.D> by a power p (a reawmable ninj^c is 
i).H to 12). h wili make the aniuiatetl reordering a little niorx! interesting m watch. 

float curveFunction (float t, float pj 
! 

return pow( 1 ■ pow((l‘t)tp] . l/p ): 

I 

You will need to determine if the user i.s view^ing tmly the 
top half of tlie table befcjre you kick off the timer in lahleView: 
animateSonFrorrL\rray: toArray;, This code just checks if the 
topmost visible row is less than 0.6 times the number of rows. 

VisibleRovfS = [inTableView rovsInRect;[InTahleView 

vislbleRect]]: 

mVievlngTop 

” NSMaxRatigefvislblGRowa) < 0,6 * [fromArray count]; 

You need to insert the following lines into table View: 
rectOfRow: detaultRect:. 

float rowPoa ([float] inRovrlndex / [oData count]]; 

// fracik>nal ptwitiim of row in table 
float rowPosAdJusted 

= mViewingTop ? (1,0 ■ towPos] : rowFos; 
float p ^ rowPosAdjusted ‘ (kCurve‘2,0] +1.0 ' hCutve; 

//c-B 0->(>,K;n/2-> 1.2 

// (p actuaJJy could range from 1.0+kCurv^c to its rucipfEXjal to In: truly symmetrical) 
t ^ curveFunctioti{t, p) ; 

To bring this all togedicr, we really want lo have both the 
curve and the sinusoidal movement. So W'hen we invoke 
curveFunction and then easeFunction together, we get movement 
as depicted in Figure 12. What more cx)uld you ask for? 



Conclusion 

Whewl Thai has been a long trip through Table Land, 
Hopefully ytju feel armed with just about everything you need 
to make your application really shine. Quite a bit of code needs 
to be added to a simple NSTableView' to get all the bells and 
whistles in [ilace, but it's still possible to keep a dean sepanition 
l>eiween your vieW'S and your controllers. Accessing your data 
from the controllers is still quite simple thanks lo Cocoa's 
Foundation KiL 

If you want lo take advantage of many of these features, 
you will find yourself needing to implement several data 
.source and delegate methods, and probably build a subclass 
for your table view that is an amalgamation of the subclasses 
presented here, And example subclass might be 
DelelableStripedTypealieadAnimatedSorringTableView, hut 
you are of course welcome to invent a shorter class name. 
(Never use a long word when you can use a diminutive one!) 

Flktheh Reference 

Many of these techniques are discussed on the two 
dominant Cocoa discussion lists, at Apple 
(http://lists,apple.com/mai[man/lfst[nfo/cocoa'dev) and OmniGroup 
(http://www.omnigroup.conn/developer/majlinglists/macosx-dev/), A 
great way to search the archives of these lists is to use 
http://cocoa.mannasam,com. Search the archives and post 
questions to these lists if you are attempting to do something 
with NSTaldeView that isn't discussed here. 

The Wely holds otlier resources relaied lo NSTableView as 
w^ell. NSTableView is discussed on ctjcoadev.ccym; Stone Hesign 
(http://www.Stone.COnn/dev/) has a subclass available online; 
OmniGroup (http://www.oninigroupxom/developer/sourcecode/) has a 
number of extensitins in their OmniAppKit ccxie; Stephane 
Sudre has some good NSTableView articles (in French) at 
http://www.niosx.nei/dev/. 
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Ten for X “ Aladdin Systems, Inc_______56 

Timbuktu Pro & netOctopus * Netopia, Inc.™.——_———41 

lime Track • Trinftnity Software—.——---56 

TlllcTrack Jukebox “ RiverSong In ter Active™_—-—.71 

Irauslation & Localization • Lingo Systems.—*..—_™*™67 

Trapeode • Trapeode Software.„..*-*.*_™™.*.™*„.*,™**.****,***„.57 

UniHelp Module ■ Electric Butterfly_____71 

Valentina * Faradigma Software™*..***.—*™___***.****.27 

VXA • Exabyte— -—--— -.*,*21 

Witsoii * Karelia Software________57 

Whistle Blower * James Sentman Software™.™**** _-_70 


Tile index on this page is proviclwl n servltx' io our readers. The publisher does not assume any liability for errors or omissions. 
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Download your free 2-user, non-expiring, full-featured copy now from www.perforce.com 
ree (and friendly) technical support is on hand to answer any and all evaluation questions. 

AJI used are either the ErademeFitSi.or regrsrened wuners. 


Perforce 


Fast Software Configuration Management www.perforce.com 


With Perforce, the fast way is always the 
fight way. Install it fast, learn tt fast, execute 
operations fast. With other SCM systems, 
developers face an unpleasant choice: 
do It the right way or do It the fast way. 

Perforce's speed and reliabilrty mean fast is right. 
See how Perforce compares with other 
leading SCM systems at 
htt p://www,perfa rce. co m/perfo rce/re vi e ws. htm I 


Run at fuli speed even with hundreds of users 
and mitlions of fifes. At the core of Perforce lies 
a relational database with well-keyed tables, 
so simple operations can be accomplished in 
near-zero time. Larger operations (like labeling 
a release and branching) are translated into 
keyed data access, giving Perforce the scalability 
that big projects require. 

IVorir anywhere. Perforce is efficient over high- 
latency networks such as WANs, the internet and 
even low-speed dial-up connections. Requiring 
only TCP/IP, Perforce makes use of a well-tuned 
streaming message protocol for synchronizing 
client workspace with server repository contents. 


Truly cross pfatform. Perforce runs on more than 
50 operating systems, including Windows and 
nearly every UNIX^ variation, from Linux' and 
Mac OS* X to AS/400 and more. 


Integrate with leading iDEs and defect trackers: 
Visual Studio. NET'', Visual C++®, Visual Basics 
JBuilder^, CodeWarrior; TeamTrack", Bugzilla™, 
ControlCenterT DevTrack'' packages, and more. 


With rival SCM systems, the only way to 
quicken the pace is to cut comers - but in the 
lung run you pay the price with missed 
deadlines, uncertain contents, buggy releases 
and no way back to previous builds. 


Develop and maintain multiple codelines. 
Perforce Inter-File Branching™ fats you merge 
new features and apply fixes between codelines. 
Smart metadata keeps track of your evolving 
projects even while they develop in paralleL 













NOT SO DESPERATELY saeklng 
ono smalt. Snex^ buy lo 

cmjft and spaik. Me 23, <;3pfiii to 
ptissibilidos aiTd raveiitHis for new 
life eKpeiiBitces, 


RON FROM SANTA FE, Vb« 
oancsict wilh. ine at llie Rattle & 
Catth? C^iib, Tbaji^s^ I was shy. Cart 
I sea yuj again? Wdi oorne d<]wri to 
fooK fOr you Friday nighi uBB^t 


AREVOU STIMULATED SY beauty, 
iiitelligedice. JujiTwr? Attraciivo SWF 
wants good looking SWM or SHM 
for romantic adventures, possWo 
long tomi E^$ontiats ivonesty. pas- 
akm, kiiKtness. serai(,i>altiy. ijitogriiy. 
openniioct wb74l 


VEGETARIAN BOWLER. VOu 
bought me a warni beor and $|aje 
ray heart Used same kind of tialt 
ar>d spoke ol hatred ot nertled 
Shews Would love 1o dwt ovei 
Ijumriius. ’05684 


SWINGING SANTA. Loiiety man 
who onHy works 6 weeks 0 year 
seeking woman with lull u'ma 
empInymsiU. with banplits lookjriota 
grow otd with man who tlthakdf Eilih 
a iMwJ lull ol jetty, ' 

WM, 95, RECENTLY WIDQWEO, 
tjKakit^ ls-30 hottid for.Call 
»|abd'm not getting any 'yoonger. 
ntVjj^ In my wtIJ. ^757 


GORGEOUS. WITTY. BORN TO 

leaso kiivit theafor, darsra?, golf, 
wamn coiivers.atiOFi !f youTe tall. 
.15-55. non smohor, financially 
secum. enjoys pajnpeny^.,44iiHftj 
IfnvfiliraQ _ 
pteasaiiritgpi--^ — 


UWN CARE? My tiushand got laTy 
and htred you fo mew our tawn 
instead you landscaped my erotic 
lanlasius In way£ f have leaver imag 
ined Ooulci notpronounce your 
name but looked very sensuai I ftad 
btiiQ atKies dh »3fi96 


ATTRACTIVE TALL (S'10"), stondOr 
DPWF; ^143, emolionally and phyai- 
-Tfiiilh lifftlT^iif appearance and 
Ihl ^cnL lov ing, des^^e3. 
Icmn tniin riffnlK^iJ% 


SIDESH' 


Holder 
Vwarkiiiq 
Mih curly 
Iwt ltjndi>'^ 


IWE: LONELY SWEDISH LINGERIE MODEC 

and gourmet cook. You: slightly overweight 
and without ambition. Must be into computers, 
role-playing games and air hockey, ^'5988 


eALMOMEO.Ydu senenatfed Itte 
oidjAlsar Ihe old people hoiirtfr 
^yflf^kend Ybu vyero a tsthbi^ 
flPr and quite unatiractlva, but 
heart is obvsousty pure gold 

_____ iijltt$t3tefwaj!dbepefie<J!ar>fliJ 

Otflafwu^gh^ BTtfV.l| ^^ll)^ pw'i i i i a i ii, petile. ■>^7807 

wicked sense nf hLimor, and a weird nWK 46, long brown Iwirrhazet 

view nf itte kiokina tor like mtr^ded eyes, 5' lid, oufolng pertionatl/iy MDNK^ TRAINER. Seeking 

person Age noi imiKirfont o 09 SM seoks OWN, 4fi-S!i. ntm smoker, tit, wcffnanTO tralri my monkay 

raiiaga educated Call mn, let s see Serloudlj^ his riaine is Murpliy and 
TREE HUGGER. MID SO'S, kplit i1 trie chomistry ifl nghJ' ’r«>05t ha is d. S year otd c^iimphnzee. Ha 

annoker, tall. Uke easy livino. tropics H3te« ppp tarts and rttfla’'people 

and I'm friendly. Suakirtp cohaider- PIimb, yoif ^ I will ihiaye.sex, 

ole, seiiii-fitcoiTipaiiiwi wilri a cJije. ’»7074. 

Mtisi love dogs find reggae ^ 


snap Bin, YgLiwnitf 


MANY WQNL 
my life - bul noT 
wonderfy wpfnan.'w 
Sfrort, prbleiBi-Dnal,’ ar« 

(rton amokah. Loi'd tjJ riaiu*. 
SINGLE MAN. Sji^to man seeking irreverant hirmnr w€77? 
single woman tor relatibinshlp, I 

enjoy daUrig^^ t^tlking qo the : recSMTLY PAROLED, ItkJi 

pfwpe to .wontan rlwt i am daring a iady who.will knap me urt 
Would a iq gfKJrmTTw M\m m 

ona n.. ■ -«dktf£tirikirr 


ARE YOU HONEST, liandseirw, 

^ni;ce,8«jiil. Imencially isecnro. iritefli- 

qan|, wU-i id havelad. CuiUiruU, ere - , ^ 

■ atjye, in, pliiyfuL udydniunjus. pati^ 

■^4eh[]itA tiumurnirR, rjirrjitcj. hiyirig, 

nj i^F, ill rrngAVTnrnrii curls 



We're Easier. 

Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic creates native compiled applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments. It's the powerful, easy-to-use tool for creating your own 
software. Each version of your software looks and works just as it should in each environment. 

Complex problems shouldn't require complex solutions, The answer is REALbasic. 


3 REALbasic4.5 


NEW VERSION 


Come see us at Macworld in MacTech Central! Download a free demo, www.realbasic.com 















